How to Include Only Specific Connections with AUTH0_INCLUDED_CONNECTIONS in Auth0 Deploy CLI

Set the AUTH0_INCLUDED_CONNECTIONS configuration property to a JSON array of connection names to restrict the Auth0 Deploy CLI to manage only those specific connections, ignoring all others during both import and export operations.

The auth0-deploy-cli tool provides granular control over which tenant assets are synchronized through inclusion filters. By configuring AUTH0_INCLUDED_CONNECTIONS, you can scope deployments to a precise subset of database and social connections without affecting the rest of your tenant's configuration.

How AUTH0_INCLUDED_CONNECTIONS Works

The CLI implements a three-phase filtering mechanism that processes the inclusion list during context initialization and applies it consistently across all operations.

Configuration Validation

When the CLI initializes, it validates that AUTH0_INCLUDED_CONNECTIONS and AUTH0_EXCLUDED_CONNECTIONS are not used simultaneously. In src/context/index.ts, the code explicitly checks for this mutual exclusivity and throws an error if both properties are defined:

// src/context/index.ts (lines 38-51)
if (config.AUTH0_INCLUDED_CONNECTIONS?.length && config.AUTH0_EXCLUDED_CONNECTIONS?.length) {
  throw new Error('Cannot define both AUTH0_INCLUDED_CONNECTIONS and AUTH0_EXCLUDED_CONNECTIONS');
}

Asset Preparation

Both the YAML and directory configuration parsers extract the inclusion list and populate an internal assets.include.connections array. In src/context/yaml/index.ts, the parser maps the configuration property directly to the assets object:

// src/context/yaml/index.ts (lines 49-51)
if (config.AUTH0_INCLUDED_CONNECTIONS) {
  this.assets.include.connections = config.AUTH0_INCLUDED_CONNECTIONS;
}

Handler Filtering

Each connection handler receives the inclusion array and filters the tenant's connections accordingly. The handler compares connection names against the list and skips any connection not explicitly included. This filtering applies identically to both export operations (when generating asset files) and import operations (when deploying to a tenant).

// Conceptual implementation based on handler logic
if (includeList.length && !includeList.includes(connection.name)) {
  // Skip this connection entirely
  return;
}

Configuration Methods

You can define AUTH0_INCLUDED_CONNECTIONS through multiple configuration mechanisms depending on your deployment workflow.

JSON Configuration File

Create a JSON configuration file containing the array of connection names to manage:

{
  "AUTH0_DOMAIN": "my-tenant.auth0.com",
  "AUTH0_CLIENT_ID": "your-client-id",
  "AUTH0_CLIENT_SECRET": "your-client-secret",
  "AUTH0_INCLUDED_CONNECTIONS": ["github", "google-oauth2", "Username-Password-Authentication"]
}

Run the CLI with the configuration flag:

a0deploy import -c config.json -i ./tenant-config/

Environment Variable

Export the inclusion list as a JSON-formatted environment variable:

export AUTH0_INCLUDED_CONNECTIONS='["github","google-oauth2"]'
a0deploy export -c config.json -o ./backup/

The CLI parses the environment variable as a JSON array before processing.

YAML Configuration

For YAML-based configurations, define the property as a list:

AUTH0_DOMAIN: my-tenant.auth0.com
AUTH0_CLIENT_ID: your-client-id
AUTH0_CLIENT_SECRET: your-client-secret
AUTH0_INCLUDED_CONNECTIONS:
  - github
  - google-oauth2
  - my-custom-database

The YAML parser in src/context/yaml/index.ts processes this list identically to the JSON array format.

Important Constraints and Limitations

Understanding the boundaries of AUTH0_INCLUDED_CONNECTIONS prevents configuration errors and ensures predictable deployments.

Mutual Exclusivity with Exclusion Lists

You cannot simultaneously define AUTH0_INCLUDED_CONNECTIONS and AUTH0_EXCLUDED_CONNECTIONS. The validation logic in src/context/index.ts explicitly prevents this combination to avoid ambiguous filtering behavior. Choose either an inclusion strategy (manage only these items) or an exclusion strategy (manage everything except these items).

Exact Name Matching

The filtering mechanism performs strict string equality comparisons against the connection name field. Wildcards, regular expressions, or partial matches are not supported. You must specify the exact connection name as it appears in the Auth0 Dashboard, including proper casing and special characters.

Impact on Both Import and Export

The inclusion list affects operations bidirectionally. During export, connections not in the list are omitted from the generated configuration files. During import, the CLI ignores existing connections not in the list and will not create, update, or delete them. This ensures consistency between your source files and the target tenant state.

Summary

• Set AUTH0_INCLUDED_CONNECTIONS to a JSON array of connection names to restrict management to only those specific connections.
• Configuration validation in src/context/index.ts prevents using inclusion and exclusion lists simultaneously.
• Asset preparation populates assets.include.connections from your configuration file or environment variable.
• Handler filtering applies the inclusion list to both import and export operations, ensuring connections outside the list are never modified or exported.
• Exact name matching is required; wildcards and patterns are not supported.

Frequently Asked Questions

Can I use AUTH0_INCLUDED_CONNECTIONS with AUTH0_EXCLUDED_CONNECTIONS?

No. The Auth0 Deploy CLI explicitly forbids using both properties simultaneously. The validation logic in src/context/index.ts checks for the presence of both arrays and throws an error if they are both defined. You must choose either an inclusion strategy (only manage specific connections) or an exclusion strategy (manage all connections except specific ones).

What happens to connections not in the include list during export?

Connections not specified in AUTH0_INCLUDED_CONNECTIONS are completely omitted from the export output. The connection handlers filter the tenant's connection list against the include array before generating YAML or directory structure files. This means your exported configuration files will only contain definitions for the included connections, ensuring that sensitive or unrelated connection configurations are not persisted to your repository.

Does AUTH0_INCLUDED_CONNECTIONS support wildcards or patterns?

No, the filtering mechanism only supports exact string matching against the connection name field. The handlers perform a simple array inclusion check (includeList.includes(connection.name)) without any regex or glob pattern support. You must specify the full, exact connection name as it appears in the Auth0 Dashboard, including proper capitalization and any special characters.

How do I verify which connections are being managed?

The most reliable method is to perform a dry-run export and inspect the generated files. Run a0deploy export with your AUTH0_INCLUDED_CONNECTIONS configuration and check that only the specified connections appear in the output directory or YAML file. Additionally, you can enable verbose logging (if supported by your version) to see which assets are being processed, though the absence of connections in the export output is the definitive confirmation that the filtering is working correctly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}