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

> Easily manage specific Auth0 connections with AUTH0_INCLUDED_CONNECTIONS in auth0-deploy-cli. Restrict imports and exports to predefined connection names for precise control.

- Repository: [Auth0/auth0-deploy-cli](https://github.com/auth0/auth0-deploy-cli)
- Tags: how-to-guide
- Published: 2026-02-25

---

**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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/index.ts), the code explicitly checks for this mutual exclusivity and throws an error if both properties are defined:

```typescript
// 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`](https://github.com/auth0/auth0-deploy-cli/blob/main/src/context/yaml/index.ts), the parser maps the configuration property directly to the assets object:

```typescript
// 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).

```typescript
// 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:

```json
{
  "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:

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

```

### Environment Variable

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

```bash
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:

```yaml
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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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`](https://github.com/auth0/auth0-deploy-cli/blob/main/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.