auth0-deploy-cli 8.4.3 → 8.5.0

package/docs/authenticating-with-tenant.md

@@ -1,34 +0,0 @@
-# Authenticating with your Tenant
-
-There are three available methods of authenticating the Deploy CLI with your tenant:
-
-- [Client Credentials](#client-credentials)
-- [Private Key JWT](#private-key-JWT)
-- [Access Token](#access-token)
-
-## Client Credentials
-
-Authenticating with a client ID and client secret pair. This option is straightforward and enables the quickest path to setup for the tool. In order to utilize, set both the `AUTH0_CLIENT_ID` and `AUTH0_CLIENT_SECRET` configuration values with the client ID and client secret respectively. These credentials can be found under the "Credentials" tab within the designated application used for the Deploy CLI.
-
-## Private Key JWT
-
-Providing a private key to facilitate asymmetric key pair authentication. This requires the "Private Key JWT" authentication method for the designated client as well as a public key configured on the remote tenant. This may be appealing to developers who do not wish to have credentials stored remotely on Auth0.
-
-To utilize, pass the path of the private key through the `AUTH0_CLIENT_SIGNING_KEY_PATH` configuration property either as an environment variable or property in your `config.json` file. This path is relative to the working directory. Optionally, you can specify the signing algorithm through the `AUTH0_CLIENT_SIGNING_ALGORITHM` configuration property.
-
-**Example: **
-
-```json
-{
-  "AUTH0_CLIENT_SIGNING_KEY_PATH": "./private.pem",
-  "AUTH0_CLIENT_SIGNING_ALGORITHM": "RSA256"
-}
-```
-
-See [Configure Private Key JWT Authentication](https://auth0.com/docs/get-started/applications/configure-private-key-jwt) for further documentation
-
-## Access Token
-
-Passing in an access token directly is also supported. This option puts more onus on the developers but can enable flexible and specific workflows when necessary. It can be leveraged by passing the Auth0 access token in via the `AUTH0_ACCESS_TOKEN` environment variable.
-
-[[table of contents]](../README.md#documentation)

package/docs/available-resource-config-formats.md

@@ -1,19 +0,0 @@
-# Available Resource Config Formats
-
-Auth0 resource state is expressed in two available different configuration file formats: YAML and JSON (aka “directory”). When using the Deploy CLI’s export command, you will be prompted with the choice of one versus the other.
-
-## YAML
-
-The YAML format is expressed mostly as a flat `tenant.yaml` file with supplemental code files for resources like actions and email templates. The single file makes tracking changes over time in version control more straightforward. Additionally, the single file eliminates a bit of ambiguity with directory and file names, which may not be immediately obvious.
-
-## Directory (JSON)
-
-The directory format separates resource types into separate directories, with each single resource living inside a dedicated JSON file. This format allows for easier conceptual separation between each type of resource as well as the individual resources themselves. Also, the Deploy CLI closely mirrors the data shapes defined in the [Auth0 Management API](https://auth0.com/docs/api/management/v2), so referencing the JSON examples in the docs may provide useful when using this format.
-
-## How to Choose
-
-The decision to select which format to use should be primarily made off of preference. Both formats are tenable solutions that achieve the same task, but with subtly different strengths and weaknesses described above. Be sure to evaluate each in the context of your context. Importantly, **this choice is not permanent**, and switching from one to the other via the import command is an option at your disposal.
-
----
-
-[[table of contents]](../README.md#documentation)

package/docs/configuring-the-deploy-cli.md

@@ -1,180 +0,0 @@
-# Configuring the Deploy CLI
-
-Configuring the Deploy’s CLI is essential for establishing Auth0 credentials as well as generally modifying the behavior of the tool to your specific needs. There are two ways the Deploy CLI can be configured:
-
-- Configuration file (`config.json`)
-- Environment variables
-
-## Configuration file
-
-A standalone JSON file can be used to configure Deploy CLI. This file will usually reside in the root directory of your project and be called `config.json`.
-
-Example **config.json** file:
-
-```json
-{
-  "AUTH0_DOMAIN": "<YOUR_TENANT_DOMAIN>",
-  "AUTH0_CLIENT_ID": "<YOUR_CLIENT_ID>",
-  "AUTH0_ALLOW_DELETE": false
-}
-```
-
-> ⚠️ **NOTE:** Hard-coding credentials is not recommended, and risks secret leakage should this file ever be committed to a public version control system. Instead, passing credentials as [environment variables](#environment-variables) is considered best practice.
-
-### Environment variables
-
-By default, the Deploy CLI ingests environment variables, providing the ability to pass credentials and other configurations to the tool without needing to publish to the `config.json` file. Environment variables can either be used to augment the `config.json` file or replace it altogether depending on the project needs.
-
-Non-primitive configuration values like `AUTH0_KEYWORD_REPLACE_MAPPINGS` and `AUTH0_EXCLUDED` can also be passed in through environment variables so long as these values are properly serialized JSON.
-
-To **disable** the consumption of environment variables for either the `import` or `export` commands, pass the `--env=false` argument.
-
-#### Examples
-
-```shell
-# Deploying configuration for YAML formats without a config.json file
-export AUTH0_DOMAIN=<YOUR_AUTH0_DOMAIN>
-export AUTH0_CLIENT_ID=<YOUR_CLIENT_ID>
-export AUTH0_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
-
-a0deploy import --input_file=local/tenant.yaml
-
-# Disable environment variable ingestion
-a0deploy export -c=config.json --format=yaml --output_folder=local --env=false
-
-# Non-primitive configuration values
-export AUTH0_EXCLUDED='["actions","organizations"]'
-export AUTH0_KEYWORD_REPLACE_MAPPINGS='{"ENVIRONMENT":"dev"}'
-a0deploy export -c=config.json --format=yaml --output_folder=local
-```
-
-### Free Tier
-
-Certain Auth0 resources require a paid plan with a verified credit card on file to manage. On free tier tenants, logStreams need to be excluded in `config.json`. You can also exclude customDomains, if you don't want to add credit card information.
-
-```json
-"AUTH0_EXCLUDED": ["logStreams", "customDomains"]
-```
-
-## Available Configuration Properties
-
-### `AUTH0_DOMAIN`
-
-String. The domain of the target Auth0 tenant.
-
-### `AUTH0_CLIENT_ID`
-
-String. The ID of the designated Auth0 application used to make API requests.
-
-### `AUTH0_CLIENT_SECRET`
-
-String. The secret of the designated Auth0 application used to make API requests.
-
-### `AUTH0_ACCESS_TOKEN`
-
-String. Short-lived access token for Management API from designated Auth0 application. Can be used in replacement to client ID and client secret combination.
-
-### `AUTH0_CLIENT_SIGNING_KEY_PATH`
-
-String. The path to the private key used by the client when facilitating Private Key JWT authentication. Path relative to the working directory. Also note `AUTH0_CLIENT_SIGNING_ALGORITHM` for specifying signing algorithm.
-
-### `AUTH0_CLIENT_SIGNING_ALGORITHM`
-
-String. Specifies the JWT signing algorithms used by the client when facilitating Private Key JWT authentication. Only used in combination with `AUTH0_CLIENT_SIGNING_KEY_PATH`. Accepted values: `RS256`, `RS384`, `PS256`.
-
-### `AUTH0_ALLOW_DELETE`
-
-Boolean. When enabled, will allow the tool to delete resources. Default: `false`.
-
-### `AUTH0_EXCLUDED`
-
-Array of strings. Excludes entire resource types from being managed, bi-directionally. See also: [excluding resources from management](excluding-from-management.md). Possible values: `actions`, `attackProtection`, `branding`, `clientGrants`, `clients`, `connections`, `customDomains`, `databases`, `emailProvider`, `emailTemplates`, `guardianFactorProviders`, `guardianFactorTemplates`, `guardianFactors`, `guardianPhoneFactorMessageTypes`, `guardianPhoneFactorSelectedProvider`, `guardianPolicies`, `logStreams`, `migrations`, `organizations`, `pages`, `prompts`, `resourceServers`, `roles`, `tenant`, `triggers`.
-
-Cannot be used simultaneously with `AUTH0_INCLUDED_ONLY`.
-
-#### Example
-
-```json
-{
-  "AUTH0_EXCLUDED": ["organizations", "connections", "hooks"]
-}
-```
-
-### `AUTH0_INCLUDED_ONLY`
-
-Array of strings. Dictates which resource types to _only_ manage, bi-directionally. See also: [excluding resources from management](excluding-from-management.md). Possible values: `actions`, `attackProtection`, `branding`, `clientGrants`, `clients`, `connections`, `customDomains`, `databases`, `emailProvider`, `emailTemplates`, `guardianFactorProviders`, `guardianFactorTemplates`, `guardianFactors`, `guardianPhoneFactorMessageTypes`, `guardianPhoneFactorSelectedProvider`, `guardianPolicies`, `logStreams`, `migrations`, `organizations`, `pages`, `prompts`, `resourceServers`, `roles`, `tenant`, `triggers`
-
-#### Example
-
-```json
-{
-  "AUTH0_INCLUDED_ONLY": ["clients", "connections", "tenant", "branding"]
-}
-```
-
-Cannot be used simultaneously with `AUTH0_EXCLUDED`.
-
-### `AUTH0_KEYWORD_REPLACE_MAPPINGS`
-
-Mapping of specific keywords to facilities dynamic replacement. See also: [keyword replacement](keyword-replacement.md).
-
-#### Example
-
-```json
-{
-  "ENVIRONMENT": "DEV",
-  "ALLOWED_ORIGINS": ["https://dev.test-site.com", "localhost"]
-}
-```
-
-### `AUTH0_PRESERVE_KEYWORDS`
-
-Boolean. When enabled, will attempt to preserve keyword replacement markers in local resource files during export. Otherwise, the remote values will overwrite those manually-placed keyword markers.
-
-This configuration requires the presence of local configuration files and defined keyword replace mappings via the `AUTH0_KEYWORD_REPLACE_MAPPINGS` configuration property.
-
-See also: [Preserving Keywords on Export](keyword-replacement.md#preserving-keywords-on-export).
-
-### `AUTH0_EXPORT_IDENTIFIERS`
-
-Boolean. When enabled, will return identifiers of all resources. May be useful for certain debugging or record-keeping scenarios within a single-tenant context. Default: `false`.
-
-### `EXCLUDED_PROPS`
-
-Provides ability to exclude any unwanted properties from management.
-
-#### Example
-
-```json
-{
-  "connections": ["options.twilio_token"]
-}
-```
-
-### `AUTH0_AUDIENCE`
-
-String. Separate value from audience value while retrieving an access token for management API. Useful when default Management API endpoints are not publicly exposed.
-
-### `AUTH0_EXCLUDED_RULES`
-
-Array of strings. Excludes the management of specific rules by ID. **Note:** This configuration may be subject to deprecation in the future. See: [excluding resources from management](excluding-from-management.md).
-
-### `AUTH0_EXCLUDED_CLIENTS`
-
-Array of strings. Excludes the management of specific clients by name. **Note:** This configuration may be subject to deprecation in the future. See: [excluding resources from management](excluding-from-management.md).
-
-### `AUTH0_EXCLUDED_DATABASES`
-
-Array of strings. Excludes the management of specific databases by name. **Note:** This configuration may be subject to deprecation in the future. See: [excluding resources from management](excluding-from-management.md).
-
-### `AUTH0_EXCLUDED_CONNECTIONS`
-
-Array of strings. Excludes the management of specific connections by name. **Note:** This configuration may be subject to deprecation in the future. See: [excluding resources from management](excluding-from-management.md).
-
-### `AUTH0_EXCLUDED_RESOURCE_SERVERS`
-
-Array of strings. Excludes the management of specific resource servers by name. **Note:** This configuration may be subject to deprecation in the future. See: [excluding resources from management](excluding-from-management.md).
-
----
-
-[[table of contents]](../README.md#documentation)

package/docs/excluding-from-management.md

@@ -1,95 +0,0 @@
-# Excluding Resources From Management
-
-In many cases, you may find it useful to exclude resources from being managed. This could be because your tenant has a large number of a particular resource and thus it is operationally burdensome to manage. Other times, you may wish to exclude them as your development workflow only pertains to a specific subset of resources and you’d like to omit all other resources for performance. Regardless of the use case, there are several options available for expressing exclusions in the Deploy CLI.
-
-## Excluding entire resources by type
-
-For more complex tenants, you may find yourself wanting to omit entire resource types. Some common use cases for wanting this capability:
-
-- Enterprise tenant with thousands of organizations, managing all would be operationally burdensome
-- CI/CD process only focuses on managing roles, you may wish to exclude all others
-- Feature development pertains to hook, you may wish to temporarily exclude all others to optimize performance
-
-This type of exclusion is expressed by passing an array of resource names into either the `AUTH0_EXCLUDED` or `AUTH0_INCLUDED_ONLY` configuration properties. The `AUTH0_EXCLUDED` configuration property excludes only the resource types provided to it. Inversely, the `AUTH0_INCLUDED_ONLY` property excludes all properties except the ones defined. Exclusion works **bi-directionally**, that is, both when export from Auth0 and importing to Auth0, regardless if resource configuration files exist or not.
-
-All supported resource values for exclusion:
-
-`actions`, `attackProtection`, `branding`, `clientGrants`, `clients`, `connections`, `customDomains`, `databases`, `emailProvider`, `emailTemplates`, `guardianFactorProviders`, `guardianFactorTemplates`, `guardianFactors`, `guardianPhoneFactorMessageTypes`, `guardianPhoneFactorSelectedProvider`, `guardianPolicies`, `logStreams`, `migrations`, `organizations`, `pages`, `prompts`, `resourceServers`, `roles`, `tenant`, `triggers`
-
-### Exclusion Example
-
-The following example excludes `clients`, `connections`, `databases` and `organizations` from being managed by the Deploy CLI. However, this example is arbitrary and your use case may require you to exclude less or more types.
-
-```json
-{
-  "AUTH0_DOMAIN": "example-site.us.auth0.com",
-  "AUTH0_CLIENT_ID": "<YOUR_AUTH0_CLIENT_ID>",
-  "AUTH0_EXCLUDED": ["clients", "connections", "databases", "organizations"]
-}
-```
-
-### Inclusion Example
-
-The following example dictates to _only_ manage `actions`, `clients` and `connections` by the Deploy CLI.
-
-```json
-{
-  "AUTH0_DOMAIN": "example-site.us.auth0.com",
-  "AUTH0_CLIENT_ID": "<YOUR_AUTH0_CLIENT_ID>",
-  "AUTH0_INCLUDED_ONLY": ["actions", "clients", "connections"]
-}
-```
-
-## Excluding single resources by ID
-
-Some resource types support exclusions of individual resource by name. This is primarily useful if you work in a multi-environment context and wish to omit a production single, specific resource from your lower-level environments. The by-Name method of exclusion is supported for rules, clients, databases, connections and resource servers with the `AUTH0_EXCLUDED_RULES` ,`AUTH0_EXCLUDED_CLIENTS`, `AUTH0_EXCLUDED_DATABASES`, `AUTH0_EXCLUDED_CONNECTIONS`, `AUTH0_EXCLUDED_RESOURCE_SERVERS` configuration values respectively.
-
-```json
-{
-  "AUTH0_DOMAIN": "example-site.us.auth0.com",
-  "AUTH0_CLIENT_ID": "<YOUR_AUTH0_CLIENT_ID>",
-  "AUTH0_EXCLUDED_CLIENTS": ["Your Application Name"],
-  "AUTH0_EXCLUDED_CONNECTIONS": ["Your Connection Name"]
-}
-```
-
-> ⚠️ **NOTE:** Excluding resources by ID is being considered for deprecation in future major versions. See the [resource exclusion proposal](https://github.com/auth0/auth0-deploy-cli/issues/451) for more details.
-
-## Omitted vs excluded vs empty
-
-The above sections pertain to exclusion which forcefully ignore configurations bi-directionally. It is worth noting similar but very different concepts: “omissions” and “empty” states.
-
-### Omission
-
-Resource configuration that is absent, either intentionally or unintentionally, will be skipped during import. That is, if you resource configuration were deleted, those configurations would be skipped during import and will not alter the remote tenant state. There is no concept of omission for exporting; unless specifically excluded, all your tenant configurations will be written to resource configuration files.
-
-### Example of omission
-
-```yaml
-roles: # roles configuration is not omitted
-  - name: Admin
-    description: Can read and write things
-    permissions: []
-  - name: Reader
-    description: Can only read things
-    permissions: []
-# The omission of all other configurations means they'll be skipped over
-```
-
-### Empty
-
-Resource configuration that is explicitly defined as empty. For set-based configurations like hooks, organizations and actions, setting these configurations to an empty set expresses an intentional emptying of those resources. In practice, this would signal a deletion, so long as the [`AUTH0_ALLOW_DELETE` deletion configuration property](configuring-the-deploy-cli.md#AUTH0_ALLOW_DELETE) is enabled.
-
-For non-set-based resource configuration like tenant, email provider and branding, the expected behavior when applying an explicitly empty configuration value will depend on the resource. The `tenant`, `branding`, `attackProtection`, and `guardianPhoneFactorSelectedProvider` resources cannot be deleted whereas the `emailProvider` resource can be deleted.
-
-#### Example of emptiness
-
-```yaml
-connections: [] # Empty connections
-tenant: {} # Effectively a no-op, cannot delete tenant
-emailProvider: {} # Will delete email provider
-```
-
----
-
-[[table of contents]](../README.md#documentation)

package/docs/how-to-contribute.md

@@ -1,49 +0,0 @@
-# How to Contribute
-
-While we may not prioritize some issues and feature requests, we are much more inclined to address them if accompanied with a code contribution. Please feel empowered to make a code contribution through a Github pull request. Please read the following for the best contributor experience.
-
-## Getting started with development
-
-The only requirement for development is having [node](https://nodejs.dev/) installed. Most modern versions will work but LTS is recommended.
-
-Once node is installed, fork the Deploy CLI repository. Once code is downloaded to local development machine, run the following commands:
-
-```shell
-npm install # Installs all dependencies
-npm run dev # Runs compiler, continuously observes source file changes
-```
-
-## Running tests
-
-In order to run the entire test suite, execute `npm run test`.
-
-To run a single test file or single test execute:
-
-```shell
-npx ts-mocha --timeout=7500 -p tsconfig.json <PATH_TO_TEST_FILE> -g=<OPTIONAL_NAME_OF_TEST>
-```
-
-### Examples
-
-```shell
-# Runs all tests within a file
-npx ts-mocha --timeout=7500 -p tsconfig.json test/tools/auth0/handlers/actions.tests.js
-
-# Runs a single test within a file
-npx ts-mocha --timeout=7500 -p tsconfig.json \
-test/tools/auth0/handlers/actions.tests.js \
--g="should create action"
-```
-
-## Code Contribution Checklist
-
-Before finally submitting a PR, please ensure to complete the following:
-
-- [ ] All code written in Typescript and compiles
-- [ ] Accompanying tests for functional changes
-- [ ] Any necessary documentation changes to pages in the /docs directory
-- [ ] PR includes thorough description about what code does and why it was added
-
----
-
-[[table of contents]](../README.md#documentation)

package/docs/keyword-replacement.md

@@ -1,83 +0,0 @@
-# Keyword Replacement
-
-The Deploy CLI supports dynamic keyword replacement with environment-specific values. This enables a scalable multi-tenant workflow where all tenants share the same resource configuration files but inject subtly different values.
-
-To use the keyword replacement, the `AUTH0_KEYWORD_REPLACEMENT_MAPPINGS` configuration property needs to contain the appropriate mappings. Then, in the resource configuration files, keywords can be injected through one of two ways:
-
-- `@@EXAMPLE_KEY@@`: Using the `@` symbols causes the tool to perform a `JSON.stringify` on your value before replacing it. So if your value is a string, the tool will add quotes; if your value is an array or object, the tool will add braces.
-- `##EXAMPLE_KEY##`: Using the `#` symbol causes the tool to perform a literal replacement; it will not add quotes or braces.
-
-### Example `config.json`
-
-```json
-{
-  "AUTH0_DOMAIN": "test-tenant.us.auth0.com",
-  "AUTH0_CLIENT_ID": "FOO",
-  "AUTH0_CLIENT_SECRET": "BAR",
-  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
-    "ENVIRONMENT": "dev",
-    "ALLOWED_LOGOUT_URLS": ["https://dev-test-site.com/logout", "localhost:3000/logout"],
-    "ALLOWED_ORIGINS": ["https://dev-test-site.com", "localhost:3000"]
-  }
-}
-```
-
-### Example `tenant.yaml`
-
-```yaml
-tenant:
-  friendly_name: "##ENVIRONMENT## tenant"
-  allowed_logout_urls: @@ALLOWED_LOGOUT_URLS@@
-  enabled_locales:
-    - en
-clients:
-  - name: Test App
-    allowed_origins: @@ALLOWED_ORIGINS@@
-    allowed_logout_urls: @@ALLOWED_LOGOUT_URLS@@
-```
-
-### Example `tenant.json`
-
-```json
-{
-  "friendly_name": "##ENVIRONMENT## tenant",
-  "allowed_logout_urls": "@@ALLOWED_LOGOUT_URLS@@"
-}
-```
-
-## Array Concatenation
-
-You may encounter situations where you would want to concatenate values onto a static array through keyword replacement. There is no special syntax to support this case, however, it is possible to achieve this by escaping double quotes in a single string that contains the appropriate values and injecting with the `##` keyword syntax. This technique works for both the [YAML and directory formats](./available-resource-config-formats.md).
-
-### Example `config.json`
-
-```json
-{
-  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
-    "GLOBAL_WEB_ORIGINS": "\"http://local.me:8080\", \"http://localhost\", \"http://localhost:3000\""
-  }
-}
-```
-
-### Example `tenant.yaml`
-
-```yaml
-clients:
-  - name: Test App
-    web_origins: [ "http://production-app.com", "https://production-app.com", ##GLOBAL_WEB_ORIGINS## ]
-```
-
-## Preserving Keywords on Export
-
-Generally, the Deploy CLI works best when operating in a uni-directional workflow from your lower-level environments (ex: dev, test) up to your production environments. However, there will be times when it is necessary to export configuration from a higher-level environment onto your local configuration directory. By default, the remote values will overwrite your local values, **causing the deletion of your keyword markers**. However, keyword replacement preservation can be enabled through the `AUTH0_PRESERVE_KEYWORDS` boolean configuration property. By enabling this configuration, the Deploy CLI will attempt to preserve the keyword markers defined in your local configuration files during export.
-
-The keyword preservation functionality will attempt to preserve as many keywords while also maintaining the accuracy of your resource configuration files. And it the majority of cases, it will work without any intervention by the user. However, some key limitations exist:
-
-- In the case of a keyword-replaced configuration field with differing values between local and remote, the local configuration value will _always_ be favored. This will cause **any out-of-band changes on remote to be wiped away** if a keyword replace marker exists anywhere in that field's value in the resource definition file; there is no "intelligent" reconciliation.
-- Arrays without a specific identifiers are not eligible for preservation. Ex: `[ "http://site.com/logout", "localhost:3000/logout", "##LOGOUT_URL##" ]`. This is because the ordering of these values are non-deterministic. Alternatively, to preserve these values, it is recommended to leverage the `@@ARRAY_REPLACE@@` keyword replace syntax with the entire value.
-
-To learn more about the history and technical challenges of of keyword preservation, refer to [RFC: Keyword Preservation During Export](https://github.com/auth0/auth0-deploy-cli/issues/688).
-
----
-
-[[table of contents]](../README.md#documentation)

package/docs/multi-environment-workflow.md

@@ -1,98 +0,0 @@
-# Incorporating Into Multi-environment Workflows
-
-The Deploy CLI supports working within a multi-tenant, multi-environment context. When integrated into your CI/CD development workflows, can be used to propagate Auth0 changes from feature development all the way through production.
-
-In general, the advised workflow is as follows:
-
-- Create a separate Auth0 tenant for each environment (ex: dev, staging, prod)
-- Create a single repository of resource configuration files for all environments
-- Add a step in your CI/CD pipeline when deploying to environments that applies the Auth0 resource configurations to the appropriate Auth0 tenant
-
-## Tenant to Environment
-
-It is recommended to have a separate Auth0 tenant/account for each environment you have. For example:
-
-| Environment | Tenant        |
-| ----------- | ------------- |
-| Development | travel0-dev   |
-| Testing     | travel0-uat   |
-| Staging     | travel0-stage |
-| Production  | travel0-prod  |
-
-## Resource configuration repository
-
-When exported, your Auth0 tenant state will be represented as a set of resource configuration files, either in a [YAML or JSON format](./available-resource-config-formats.md). In a multi-environment context it is expected to have a single repository of resource configurations that is applied to all environments. In practice, this may exist as a directory in your project’s codebase or in a separate codebase altogether.
-
-You should have at least one branch for each tenant in your repository, which allows you to make changes without deploying them (the changes would only deploy when you merged your branch into the master, or primary, branch). With this setup, you can have a continuous integration task for each environment that automatically deploys changes to the targeted environment whenever the master branch receives updates.
-
-Your workflow could potentially look something like this:
-
-1. Make changes to development.
-2. Merge changes to testing (or `uat`).
-3. Test changes to `uat`. When ready, move and merge the changes to `staging`.
-4. Test `staging`. When ready, move and merge the changes to `production`.
-
-You may want to set your production environment to deploy only when triggered manually.
-
-## Uni-directional Flow
-
-The multi-environment workflow works best when changes are propagated “up” in a single direction. Changes to the resource configuration files should first be applied to the lowest level environment (ex: dev) and then incrementally applied up through all other environments until applied to production. This uni-directional practice ensures sufficient testing and approval for changes to your tenant. Once set, it is recommended to not apply configurations directly to production through other means such as the Auth0 Dashboard or Management API unless those changes are captured by a subsequent Deploy CLI export. Otherwise, those changes are subject to overwrite.
-
-## Environment-specific values
-
-While it is expected that all environments will share the same set of resource configuration files, environment-specific values can be expressed through separate tool configuration files and dynamic [keyword replacement](keyword-replacement.md).
-
-### Separate Config Files
-
-Specifying a separate tool configuration file per environment can be used to keep the resource configuration files agnostic of environment but still cater for the needs of each environment. At a minimum, you will need to provide separate credentials for each environment, but it is also possible to exclude certain resources, enable deletion and perform dynamic keyword replacement on a per-environment basis.
-
-### Example file structure
-
-```
-project-root
-│
-└───auth0
-│   │   config-dev.json   # Dev env config file
-│   │   config-test.json  # Test env config file
-│   │   config-prod.json  # Prod env config file
-│   │   ... all other resource configuration files
-│
-└───src
-    │   ... your project code
-```
-
-### Dynamic Values via Keyword Replacement
-
-Once separate configurations files are adopted for each environment, keyword replacement via the `AUTH0_KEYWORD_REPLACE_MAPPINGS` configuration property can be used to express the dynamic replacement values depending on the environment. For example, you may find it necessary to have a separate set of allowed origins for your clients (see below). To learn more, see [Keyword Replacement](keyword-replacement.md).
-
-#### Example `config-dev.json`
-
-```json
-{
-  "AUTH0_DOMAIN": "travel0-dev.us.auth0.com",
-  "AUTH0_CLIENT_ID": "PdwQpGy62sHcsV6ufZNEVrV4GDlDhm74",
-  "AUTH0_ALLOW_DELETE": true,
-  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
-    "ENV": "dev",
-    "ALLOWED_ORIGINS": ["http://localhost:3000", "http://dev.travel0.com"]
-  }
-}
-```
-
-#### Example `config-prod.json`
-
-```json
-{
-  "AUTH0_DOMAIN": "travel0.us.auth0.com",
-  "AUTH0_CLIENT_ID": "vZCEFsDYzXc1x9IomB8dF185e4cdVah5",
-  "AUTH0_ALLOW_DELETE": false,
-  "AUTH0_KEYWORD_REPLACE_MAPPINGS": {
-    "ENV": "prod",
-    "ALLOWED_ORIGINS": ["http://travel0.com"]
-  }
-}
-```
-
----
-
-[[table of contents]](../README.md#documentation)