How the AUTH0_INCLUDED_ONLY Option Restricts Deployments in Auth0-Deploy-CLI

The AUTH0_INCLUDED_ONLY configuration option acts as a whitelist that restricts the Auth0 Deploy CLI to process only explicitly listed resource types during both import and export operations, ignoring all other assets.

The AUTH0_INCLUDED_ONLY option in the auth0/auth0-deploy-cli repository provides a precise mechanism for limiting deployment scope to specific Auth0 resource types. This configuration flag ensures that only explicitly listed assets—such as clients, connections, or tenant settings—are processed during import and export operations, while all other resources are systematically excluded from the deployment lifecycle.

Understanding the AUTH0_INCLUDED_ONLY Configuration Option

The AUTH0_INCLUDED_ONLY option accepts an array of resource type strings that define exactly which handlers the Deploy CLI should execute. When this option is defined, the CLI enters a whitelist mode where any resource type not explicitly included in the array is treated as excluded. This behavior applies symmetrically to both loading local assets into Auth0 (import) and dumping Auth0 configurations to local files (export).

How AUTH0_INCLUDED_ONLY Works Under the Hood

The implementation of AUTH0_INCLUDED_ONLY spans multiple layers of the CLI architecture, from initial configuration validation through final asset processing.

Configuration Validation in src/context/index.ts

Before any deployment operations begin, the CLI validates the AUTH0_INCLUDED_ONLY configuration in src/context/index.ts. The validation ensures the array is not empty and enforces mutual exclusivity with AUTH0_EXCLUDED, preventing ambiguous configuration states.

if (config.AUTH0_INCLUDED_ONLY.length === 0) {
  throw new Error('Need to define at least one resource type …');
}
if (hasExcludedResources && hasIncludedResources) {
  throw new Error('Both AUTH0_EXCLUDED and AUTH0_INCLUDED_ONLY …');
}

Filtering Local Assets During Import

When loading local assets from YAML or directory structures, the CLI applies the inclusion filter to determine which handlers to invoke. In src/context/yaml/index.ts and src/context/directory/index.ts, the filterOnlyIncludedResourceTypes function intercepts the handler list before asset parsing begins.

Object.entries(handlers)
  .filter(([handlerName]) => !excludedAssetTypes.includes(handlerName))
  .filter(filterOnlyIncludedResourceTypes(this.config.AUTH0_INCLUDED_ONLY))
  .forEach(([_, handler]) => { … });

If a resource type is not present in the AUTH0_INCLUDED_ONLY array, its handler is never invoked, ensuring the asset never enters the in-memory assets object.

Restricting Export Operations

During export operations, the same filtering logic applies when dumping Auth0 configurations to local files. The CLI iterates over handlers in src/context/yaml/index.ts and src/context/directory/index.ts, skipping any resource types not explicitly included.

Object.entries(handlers)
  .filter(([handlerName]) => !excludedAssetTypes.includes(handlerName))
  .filter(filterOnlyIncludedResourceTypes(this.config.AUTH0_INCLUDED_ONLY))
  .map(async ([name, handler]) => { … });

The filterOnlyIncludedResourceTypes Utility

The core filtering logic resides in src/context/index.ts as a higher-order function that returns true for every handler when AUTH0_INCLUDED_ONLY is undefined, otherwise checking membership in the included array.

export const filterOnlyIncludedResourceTypes = (includedAssetTypes) => ([handlerName]) => {
  if (includedAssetTypes === undefined) return true;
  return includedAssetTypes.includes(handlerName);
};

Practical Implementation Examples

Basic Configuration

To restrict deployments to specific resource types, define the AUTH0_INCLUDED_ONLY array in your configuration file:

{
  "AUTH0_DOMAIN": "my-tenant.auth0.com",
  "AUTH0_CLIENT_ID": "...",
  "AUTH0_CLIENT_SECRET": "...",
  "AUTH0_INPUT_FILE": "./local/",
  "AUTH0_INCLUDED_ONLY": ["clients", "connections", "tenant"]
}

This configuration ensures only clients, connections, and tenant assets are processed during import or export operations.

Running Import and Export Commands

Execute the CLI with the restricted configuration:

# Export only the whitelisted types

npm run build && node lib/index.js export -c config.json -f yaml -o ./exported/

The CLI performs three validation steps:

1. Verifies AUTH0_INCLUDED_ONLY is non-empty (validation in src/context/index.ts)
2. Filters handlers using filterOnlyIncludedResourceTypes to exclude non-listed resource types
3. Generates output containing only the specified sections

Error Handling for Invalid Configurations

Attempting to use both exclusion and inclusion flags simultaneously results in an immediate error:

{
  "AUTH0_EXCLUDED": ["rules"],
  "AUTH0_INCLUDED_ONLY": ["clients"]
}

The CLI aborts with the message:

Both AUTH0_EXCLUDED and AUTH0_INCLUDED_ONLY configuration values are defined, only one can be configured at a time.

This validation occurs in src/context/index.ts before any deployment operations begin.

Summary

• AUTH0_INCLUDED_ONLY acts as a whitelist that restricts the Auth0 Deploy CLI to process only explicitly listed resource types.
• The option is validated in src/context/index.ts to ensure it is non-empty and mutually exclusive with AUTH0_EXCLUDED.
• During import operations, the CLI filters handlers in src/context/yaml/index.ts and src/context/directory/index.ts to load only included assets.
• During export operations, the same filtering logic ensures only specified resource types are written to output files.
• The filterOnlyIncludedResourceTypes utility function in src/context/index.ts provides the core filtering mechanism, returning true for all handlers when the option is undefined.

Frequently Asked Questions

What happens if AUTH0_INCLUDED_ONLY is undefined?

When AUTH0_INCLUDED_ONLY is undefined, the filterOnlyIncludedResourceTypes utility returns true for every handler, allowing the CLI to process all resource types. This maintains backward compatibility and default behavior where no restrictions are applied.

Can I use AUTH0_INCLUDED_ONLY with AUTH0_EXCLUDED?

No, these options are mutually exclusive. The CLI validates this constraint in src/context/index.ts and throws an error if both are defined simultaneously. This prevents ambiguous configuration states where a resource type might appear in both lists.

Which resource types can I include in AUTH0_INCLUDED_ONLY?

You can include any valid Auth0 resource type that the Deploy CLI supports, such as clients, connections, tenant, rules, hooks, resourceServers, clientGrants, guardian, roles, users, organizations, and actions. The specific available types depend on your CLI version and Auth0 tenant configuration.

Does AUTH0_INCLUDED_ONLY affect both import and export operations?

Yes, the option applies bi-directionally. During import (deploy), the CLI filters which handlers load local assets into Auth0. During export (dump), the same filter restricts which resource types are written to local files. This ensures consistent behavior regardless of operation direction.

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