AUTH0_INCLUDED_CONNECTIONS has no effect on export, despite docs stating it applies to both export and import

[jithinzac]

Checklist

• I have looked into the README and have not found a suitable solution or answer.
• I have looked into the documentation and have not found a suitable solution or answer.
• I have searched the issues and have not found a suitable solution or answer.
• I have upgraded to the latest version of this tool and the issue still persists.
• I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• I agree to the terms within the Auth0 Code of Conduct.

Description

AUTH0_INCLUDED_CONNECTIONS is only applied on import. It has no effect on export, despite the documentation stating that it affects both.

docs/configuring-the-deploy-cli.md says:

When configured, only the connections listed by name will be included in export and import operations. All other connections in the tenant will be completely ignored.

Important: This setting affects all operations (export and import). Connections not in this list will not appear in exports and will not be modified during imports.

The import half is implemented and works. The export half is not implemented in any published version.

The value is read into assets.include.connections on both code paths, including inside dump():

// src/context/directory/index.ts:124-126 (inside dump)
this.assets.include = {
  connections: this.config.AUTH0_INCLUDED_CONNECTIONS || [],
};

…but filterIncluded has exactly one call site, in the import path:

// src/tools/auth0/handlers/connections.ts:930-936
async processChanges(assets: Assets): Promise<void> {
  ...
  const includedConnections = (assets.include && assets.include.connections) || [];
  const excludedConnections = (assets.exclude && assets.exclude.connections) || [];
  let changes = await this.calcChanges(assets);
  changes = filterExcluded(changes, excludedConnections);
  changes = filterIncluded(changes, includedConnections);   // only call site

filterIncluded operates on CalculatedChanges ({del, update, create, conflicts}), a structure the export path never builds.

Both dump() implementations read assets.exclude and never assets.include:

// src/context/directory/handlers/connections.ts:69-75
// Filter excluded connections
const excludedConnections = (context.assets.exclude && context.assets.exclude.connections) || [];
if (excludedConnections.length) {
  connections = connections.filter(
    (connection) => !excludedConnections.includes(connection.name)
  );
}
// -> every remaining connection is then written to disk

Same in src/context/yaml/handlers/connections.ts:56-62.

An exhaustive grep of src/ on master (a8a602f) shows four references total: two writes into assets.include, the mutual-exclusion validation against AUTH0_EXCLUDED_CONNECTIONS, and one read inside processChanges. Identical in 8.29.2, 8.41.0, and 9.0.0-beta.1.

This is a notable asymmetry, since AUTH0_EXCLUDED_CONNECTIONS — documented as the deprecated counterpart — did gain export filtering, along with folder pruning that preserves excluded connections' files across re-dumps.

Expectation

With AUTH0_INCLUDED_CONNECTIONS configured, a0deploy export writes only the listed connections, and leaves connections outside the list unmanaged — mirroring how AUTH0_EXCLUDED_CONNECTIONS behaves on export today.

This matters most for the use case the docs call out explicitly — "Managing only specific connections while preserving others (e.g., self-service SSO connections)". A keep-list is the only maintainable shape there: Self-Service SSO mints new connections with generated UUID names over time, so expressing the same intent via AUTH0_EXCLUDED_CONNECTIONS requires amending the exclude list every time a connection is created. And the two cannot be combined — src/context/index.ts:148 throws if both are set.

Concretely, on a tenant with 4 social/enterprise connections we manage plus 27 UUID-named samlp connections created by Self-Service SSO, export writes all 31 regardless of the include list.

Reproduction

1. On a tenant with more than one connection, configure only a subset:

   {
     "AUTH0_DOMAIN": "<tenant>.us.auth0.com",
     "AUTH0_CLIENT_ID": "<client-id>",
     "AUTH0_INCLUDED_CONNECTIONS": ["google-oauth2", "windowslive"]
   }

2. Export:

   a0deploy export --config_file=config.json --format=directory --output_folder=local

3. local/connections/ contains a .json file for every connection on the tenant, not just google-oauth2.json and windowslive.json.

Same result with --format=yaml — every connection appears under connections: in the output.

import correctly restricts changes to the two listed connections, so the discrepancy is export-only.

Deploy CLI version

8.41.0 (also verified on 8.29.2 and 9.0.0-beta.1)

Node version

22

Additional context

Happy to open a PR implementing the export-side filter in both the directory and yaml handlers, mirroring the existing exclude behaviour — including preserving files of unmanaged connections across re-dumps so the new pruning logic doesn't delete them. Let me know if you'd prefer the fix, or a documentation correction instead.

[harshithRai]

Thank you for raising this @jithinzac!
I also noticed the PR you have raised associated with this. I will review the issue and linked PR shortly and be back with an update.

Your contributions are much appreciated!