
Support
This integration is community supported. Learn more
GitHub Actions
Use the Auth0 Deploy CLI with GitHub Actions to manage Auth0
Automate, customize, and execute your software development workflows right in your repository with GitHub Actions. You can discover, create, and share actions to perform any job you'd like, including CI/CD, and combine actions in a completely customized workflow.
The Auth0 Deploy CLI provides the ability to manage your Auth0 configuration from CLI and can easily be integrated into a GitHub Action. Instead of working through a UI, you can create, update, and manage your Auth0 applications, APIs, and more through code stored in a Git repository on GitHub, managed by Auth0 Deploy CLI, and automated by GitHub Actions.
Support
This integration is community supported. Learn more
Prerequisites
Before you get started, you'll need:
- An Auth0 account. You can sign up for free.
- A GitHub account. You can sign up for free.
- A local development environment with tools including Git for source version control, and Node.js and
npm
to install and run the Auth0 Deploy CLI locally.
Configuring your Auth0 tenants
When building applications using Auth0, we recommend creating a dedicated Auth0 tenant per environment. Doing so allows you to isolate your production user base from your other environments and configure different administrators per environment (e.g., engineers might not have access to production configuration).
In this guide, we'll have three different Auth0 tenants:
- zerohr-dev.us.auth0.com: Tenant used by developers. This is where manual changes happen.
- zerohr-staging.us.auth0.com: Tenant used by the Product Manager and QA team.
- zerohr-prod.us.auth0.com: Tenant used by end users/customers.
The Auth0 Deploy CLI will need the client_id
and client_secret
credentials to get access to the Management API for each of the tenants. Please install and configure the Auth0 Deploy CLI and retrieve the credentials before moving on to the next step.
Initial export
Once we have the client credentials for the development tenant, we can use the Auth0 Deploy CLI to perform an initial export.
Let's start by creating a config file, which contains the client_id
and client_secret
in the development tenant. We can use the EXCLUDED_PROPS
setting to avoid exporting any secrets:
{
"AUTH0_DOMAIN": "zerohr-dev.us.auth0.com",
"AUTH0_CLIENT_ID": "fU8QR25rCTR8k7RhhURNqzUE0sBtJTSR",
"AUTH0_CLIENT_SECRET": "...",
"EXCLUDED_PROPS": {
"clients": ["client_secret"],
"connections": ["options.client_secret"]
}
}
Then create a directory, initialize it as a Git repo, and run the a0deploy
command to export your Auth0 configurations:
$ mkdir github-actions-auth0-deploy
$ cd github-actions-auth0-deploy
$ git init
$ a0deploy export -c config.json --strip --format yaml --output_folder .
The last command (a0deploy export
) calls the Auth0 Deploy CLI, which will iterate over all the resources in our Auth0 tenant and export them to a single yaml
file, and create some files for additional assets in the tenant (for example, a *.js
file for each of your rules and hooks).
The following is an excerpt that demonstrates what such an exported tenant.yaml
configuration file could look like:
rules:
- name: custom-claims
script: ./rules/custom-claims.js
stage: login_success
enabled: true
order: 1
resourceServers:
- name: ZeroHR API
identifier: 'https://api.dev.zerohr.app/'
allow_offline_access: false
signing_alg: RS256
skip_consent_for_verifiable_first_party_clients: true
token_lifetime: 86400
token_lifetime_for_web: 7200
Moving to GitHub
We now have everything we need to create a GitHub repository containing the following:
- The configuration for dev/staging/production
- The
yaml
file, and the other files created by the Auth0 Deploy CLI - The GitHub Actions workflows
We'll also create a dedicated config
folder containing all the configuration files:
./config/dev.json
./config/prod.json
./config/staging.json
Each configuration file will contain the domain and the client_id
. Note that the client_secret
should not be added here; we'll manage that using GitHub encrypted secrets, not directly in source control.
{
"AUTH0_DOMAIN": "zerohr-staging.us.auth0.com",
"AUTH0_CLIENT_ID": "Y13eh0EhojdF1Bti06FLJJ1jZx0Pb0hJ",
"AUTH0_ALLOW_DELETE": true,
"AUTH0_KEYWORD_REPLACE_MAPPINGS": {
"APP_CALLBACKS": ["https://www.staging.zerohr.app", "https://staging.zerohr.app"],
"API_IDENTIFIER": "https://api.staging.zerohr.app/"
},
"EXCLUDED_PROPS": {
"clients": ["client_secret"],
"connections": ["options.client_secret"]
}
}
Also notice AUTH0_KEYWORD_REPLACE_MAPPINGS
, which allows us to include environment-specific settings that will be injected into the yaml
file. This can be useful if, for example, the applications in our environments have different URLs. The URLs can be managed here and then injected into the template as we deploy to a specific environment.
For this to work, we need to modify the yaml
file and replace the actual values of the URLs with variables. The ##var##
format will be replaced with a string literal, the @@var@@
format with a JSON representation of the variable (in this case, an actual array). Below is an example of the tenant.yaml
configuration file with the mapping enabled:
resourceServers:
- name: ZeroHR API
identifier: '##API_IDENTIFIER##'
allow_offline_access: false
signing_alg: RS256
skip_consent_for_verifiable_first_party_clients: true
token_lifetime: 86400
token_lifetime_for_web: 7200
clients:
- name: ZeroHR App
app_type: spa
callbacks: @@APP_CALLBACKS@@
client_aliases: []
cross_origin_auth: false
custom_login_page_on: true
grant_types:
- authorization_code
- refresh_token
is_first_party: true
You can read more about how environment variables and keyword mappings work with the Auth0 Deploy CLI in the Auth0 Deploy CLI documentation.
GitHub Actions and Continuous Delivery
To make local testing easier, we can move the a0deploy
commands to a package.json
file:
{
"scripts": {
"export:dev": "a0deploy export --strip --format yaml --output_folder . --config_file ./config/dev.json",
"import:dev": "a0deploy import --input_file tenant.yaml --config_file ./config/dev.json",
"import:staging": "a0deploy import --input_file tenant.yaml --config_file ./config/staging.json",
"import:prod": "a0deploy import --input_file tenant.yaml --config_file ./config/prod.json"
}
}
This will allow us to use npm run import:prod
, for example, to import and deploy the configurations for the prod
environment.
The Auth0 Deploy CLI will need to use the client_id
and client_secret
for the given environment to access the Management API, which is used to create/update/delete resources. The client_secret
is aptly named--it is a secret and should not be stored in source control. So for each environment, we'll create a GitHub encrypted secret in the repository to store the client_secret
, for example, PROD_AUTH0_CLIENT_SECRET
for prod
environment:
As a final step, we'll create a GitHub Actions workflow in the .github/workflows
directory for each environment to install and run the Auth0 Deploy CLI.
For example, we create a file named .github/workflows/auth0-staging.yml
with the following content for the staging environment:
name: Deploy to Auth0 staging account
on:
push:
branches: [staging]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Download files from the current repository
uses: actions/checkout@v2
- name: Install Node.js
uses: actions/setup-node@v1
with:
node-version: '14.x'
- name: Install the auth0-deploy-cli
run: npm install -g auth0-deploy-cli
- name: Import changes to the Auth0 staging account
env:
AUTH0_CLIENT_SECRET: ${{ secrets.STAGING_AUTH0_CLIENT_SECRET }}
run: npm run import:staging
Please refer to Quickstart for GitHub Actions for more details on creating workflows for GitHub Actions.
Deployment
The GitHub Actions workflow will run whenever there is a push to the branches dev
, staging
, and prod
. As a simple test, we can modify one setting in our Auth0 configuration and push the change to the staging branch:
$ git checkout -b staging
$ git add tenant.yaml
$ git commit -m "chore: multiple environment support"
$ git push -u origin staging
Immediately after pushing the change, we can see that a new job for the Deploy to Auth0 staging account
workflow has started:
Further reading and documentation
Support
This integration is community supported. Learn more