GitHub Actions

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.

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

• Auth0 Deploy CLI Tool
• Quickstart for GitHub Actions