--config_file meaning in deploy cli commands

Get Help
,
1

Hi all.

I have almost finished my project for work which involves getting my team to make Auth0 changes through the Deploy CLI, pushing their autogenerated files to our ADO repo and then getting the pipeline I made to deploy this to the tenants.

It is looking good so far as I managed to get the pipeline to deploy to the staging tenant although I haven’t yet been authorised by our Test Manager to try the Dev/Prod ones yet.

In any case, I am confused by something: when you do the import command, what does ‘–config_file’ do?

I put in a line into the YAML pipeline file that says ‘a0deploy import --config_file=tenant/config-staging.json --input_file=tenant.yaml’ . I know this line makes it so the pipeline accesses the tenant.yaml file and therefore knows to deploy that config, but what exactly is ‘config_file=tenant/config-staging.json’ doing? What does it do and why does it need to be there? Do I need to change it for the deployments to the other tenants?

3

Hi @shayan.bhattacharya

The --config_file parameter tells the Deploy CLI where to deploy your changes and how to authenticate to that specific tenant. While your tenant.yaml holds the actual configuration you want to build (the “what”), the config-staging.json file holds the “keys” to your Auth0 Staging tenant. You will absolutely need different configuration files (or environment variables) for your Dev and Prod tenants.

To understand why both files are necessary, it helps to look at the separation of concerns within the Auth0 Deploy CLI:

  1. The Payload (--input_file=tenant.yaml): This file is environmentally agnostic. It contains the descriptions of your applications, APIs, Actions, and rules. Ideally, this file remains exactly the same whether you are pushing to Dev, Staging, or Prod.

  2. The Environment Constraints (--config_file=tenant/config-staging.json): This file contains the tenant-specific metadata. For the Deploy CLI to make changes via the Auth0 Management API, it needs to authenticate as a Machine-to-Machine (M2M) application residing in that specific target tenant.

If you were to open config-staging.json, you would typically see fields like:

  • AUTH0_DOMAIN: The URL of your Staging tenant (e.g., my-company-staging.eu.auth0.com).

  • AUTH0_CLIENT_ID: The ID of the Deploy CLI application in the Staging tenant.

  • AUTH0_CLIENT_SECRET: The secret for that Deploy CLI application.

  • AUTH0_KEYWORD_REPLACE_MAPPINGS: Environment-specific variables (like staging callback URLs vs. production callback URLs) that get injected into your tenant.yaml during deployment.

To answer your specific questions:

What does it do and why does it need to be there?
It acts as the authentication module for the CLI. Without it, the a0deploy command has a set of instructions (tenant.yaml) but no idea which Auth0 tenant to send them to, nor the authorization credentials required to apply them.

Do I need to change it for the deployments to other tenants?
Yes, absolutely. Because your Dev and Prod tenants have entirely different AUTH0_DOMAIN names and require distinct AUTH0_CLIENT_ID and AUTH0_CLIENT_SECRET credentials, you must instruct the pipeline to use the correct config for the correct stage.

When your Test Manager gives you the green light, your ADO pipeline steps will look something like this:

  • Dev Deployment: a0deploy import --config_file=tenant/config-dev.json --input_file=tenant.yaml

  • Staging Deployment: a0deploy import --config_file=tenant/config-staging.json --input_file=tenant.yaml

  • Prod Deployment: a0deploy import --config_file=tenant/config-prod.json --input_file=tenant.yaml

In conclusion:
\1. Understand that --config_file (or -c for short) specifies the configuration file that contains the Auth0 credentials and connection details for the tenant you are deploying to, not the tenant configuration you are deploying.
2. Recognize that the --config_file parameter points to a JSON file (such as tenant/config-staging.json) that contains AUTH0_DOMAIN, AUTH0_CLIENT_ID, AUTH0_CLIENT_SECRET, and other authentication settings needed for the Deploy CLI to connect to and authenticate with your Auth0 tenant.
3. Know that the --input_file parameter (in your case tenant.yaml) specifies the tenant configuration you want to deploy — the actual Auth0 resources, rules, connections, and settings — while --config_file specifies how to authenticate to the target tenant.
4. Yes, you must change the --config_file parameter for each tenant deployment, because each tenant (staging, dev, production) has different credentials and domain values, and you need a separate config.json file for each one.
5. Create separate configuration files for each tenant environment:

  • tenant/config-staging.json for staging deployments
  • tenant/config-dev.json for dev deployments
  • tenant/config-prod.json for production deployments
  1. Update your pipeline YAML to use the correct --config_file for each deployment stage, for example:
    • Staging stage: a0deploy import --config_file=tenant/config-staging.json --input_file=tenant.yaml
    • Dev stage: a0deploy import --config_file=tenant/config-dev.json --input_file=tenant.yaml
    • Prod stage: a0deploy import --config_file=tenant/config-prod.json --input_file=tenant.yaml
  2. Review the Auth0 documentation on configuring the Deploy CLI to understand the structure of the config.json file and the required credentials.

Kind Regards,
Nik