GitHub Deployments

GitHub Deployments

The GitHub Deployments extension allows you to deploy rules, rules configs, connections, database connection scripts, clients, client grants, resource servers, hosted pages and email templates from GitHub to Auth0. You can configure a GitHub repository, keep all your rules and database connection scripts there, and have them automatically deployed to Auth0 each time you push to your repository.

You can use the auth0-deploy-cli tool to export and import tenant configuration data to a directory structure or a YAML file. For more information, see Deploy CLI Tool Overview.

Configure the extension

To install and configure this extension, click on the GitHub Deployments box in the list of provided extensions on the Extensions page of the dashboard. The Install Extension window will open.

Install Github Deployments Extension

Set the following configuration variables:

  • REPOSITORY: The repository from which you want to deploy rules and database scripts. This can be either a public or private repository.
  • BRANCH: The branch that the extension will monitor for commits.
  • HOST: The public accessible GitHub Enterprise (version 2.11.3 and later) hostname, no value is required when using (optional).
  • API_PATH: GitHub Enterprise API path prefix, no value is required when using (optional).
  • TOKEN: Your GitHub Personal Access Token. Follow the instructions at [Creating an Access Token] ( to create a token with repo scope.
  • BASE_DIR: The base directory, where all your tenant settings are stored
  • AUTO_REDEPLOY: If enabled, the extension redeploys the last successful configuration in the event of a deployment failure. Manual deployments and validation errors does not trigger auto-redeployment
  • SLACK_INCOMING_WEBHOOK_URL: The Webhook URL for Slack, used to receive Slack notifications for successful and failed deployments (optional).

Some of the configuration variables were changed in version 2.6.0 of this extension. If you are updating the extension from a prior version, make sure that you update your configuration accordingly.

Once you have provided this information, click Install.

Navigate to the Extensions page and click on the Installed Extensions tab.

Click on the row for the GitHub Deployments extension. The first time you click on your installed extension, you will be asked to grant it to access your GitHub account.

Grant Github Access

Once you agree, you will be directed to the GitHub Integration configuration page.

Configure Extension

The Configuration page will display the settings you will need to create a webhook in your GitHub repository pointing to the extension.

Copy these values into the Add Webhook page for your GitHub repository:

Add Webhook

You can find details on how to configure a webhook at Creating Webhooks on GitHub.


Once you have set up the webhook in GitHub using the provided information, you are ready to start committing to your repository.

With each commit you push to your configured GitHub repository, the webhook will call the extension to initiate a deployment if changes were made to one of these folders:

  • clients
  • grants
  • emails
  • resource-servers
  • connections
  • database-connections
  • rules-configs
  • rules
  • pages

The Deploy button on the Deployments tab of the extension allows you to manually deploy the rules and database connection scripts you already have in your GitHub repository. This is useful if you already have a repository filled with scripts that you want to deploy once you have set up the extension, or if you have accidentally deleted some scripts in Auth0 and need to redeploy the latest version of your repository.

Deleting Rules and Scripts from GitHub

To maintain a consistent state, the extension will always do a full redeployment of the contents of these folders. Any rules or database connection scripts that exist in Auth0 but not in your GitHub repository will be deleted.

Deploy Database Connection scripts

To deploy database connection scripts, you must first create a directory under database-connections. The name of the directory must exactly match the name of your database connection in Auth0. Of course, you can create as many directories as you have database connections.

Under the created directory, create one file for every script you want to use. The allowed scripts are:

  • get_user.js
  • create.js
  • verify.js
  • login.js
  • change_password.js
  • delete.js

Only the login.js script is required in a custom database connection.

If you enabled the migration feature, you will also need to provide the get_user.js script.

You can find an example in this GitHub repository.

Deploy Database Connection settings

To deploy Database Connection settings, you must create database-connections/[connection-name]/settings.json.

This will work only for Auth0 connections (strategy === auth0); for non-Auth0 connections use connections.

See Management API v2 Docs for more info on allowed attributes for Connections.

Deploy Connections

To deploy a connection, you must create a JSON file under the connections directory of your GitHub repository. Example:


  "name": "facebook",
  "strategy": "facebook",
  "enabled_clients": [
  "options": {}

The enabled_clients array, when used directly with the Management API v2, is a list of client IDs for which the connection is enabled. As an added convenience, the deployment extension will attempt to match entries in the enabled_clients array by client name and replace them with the appropriate client ID when a match is found, allowing you to specify "my-client-name" instead of "my-client-id" to refer to each application.

This will work only for non-Auth0 connections (strategy !== auth0); for Auth0 connections, use database-connections.

See Management API v2 Docs for more info on allowed attributes for Connections.

Deploy Universal Login Pages

The supported pages are:

  • error_page
  • guardian_multifactor
  • login
  • password_reset

To deploy a page, you must create an HTML file under the pages directory of your GitHub repository. For each HTML page, you need to create a JSON file (with the same name) that will be used to mark the page as enabled or disabled. For example, to deploy a password_reset, you would create two files:


To enable the page, the password_reset.json would contain the following:

  "enabled": true

The error_page cannot be enabled/disabled. To use the default error page, remove the content of error_page.html.

Deploy rules

To deploy a rule, you must first create a JavaScript file under the rules directory of your GitHub repository. Each rule must be in its own JavaScript file.

For example, if you create the file rules/set-country.js, then the extension will create a rule in Auth0 with the name set-country.

If you plan to use Source Control integration for an existing account, first rename your rules in Auth0 to the same name of the files you will be deploying to this directory.

You can control the rule order and status (enabled/disabled) by creating a JSON file with the same name as your JavaScript file. For this example, you would create a file named rules/set-country.json.


function (user, context, callback) {
  if (context.request.geoip) { = context.request.geoip.country_name;
  callback(null, user, context);


  "enabled": false,
  "order": 15,
  "stage": "login_success"

You can find examples in this GitHub repository.

Set the order

Multiple rules of the same order are not allowed. To avoid conflicts, you can create a JSON file for each rule and assign a value for order. If you leave enough space between these values, re-ordering them without conflicts will be easier. For example, if you have three rules, instead of setting their order to 1, 2, 3, you can set them to 10, 20, 30. This way, to move the 30 rule before the 20, you can simply change its order to any value between 11 and 19.

Deploy Rules Configs

To deploy a rule config, you must create a JSON file under the rules-configs directory of your GitHub repository. Example:


  "key": "secret_number",
  "value": "42"

Deploy Clients

To deploy a client, you must create a JSON file under the clients directory of your GitHub repository. Example:


  "name": "my-client"

See Management API v2 Docs for more info on allowed attributes for Clients and Client Grants.

Deploy Clients Grants

You can specify the client grants for each client by creating a JSON file in the grants directory.


  "client_id": "my-client",
  "audience": "",
    "scope": [

The deployment extension accepts an application name instead of the client ID in the client_id property. It will try to match the name to an existing application before creating the Client Grant.

Deploy Resource Servers

To deploy a resource server, you must create a JSON file under the resource-servers directory of your GitHub repository. Example:


  "name": "my-api",
  "identifier": "",
  "scopes": [
      "value": "read:users",
      "description": "Allows getting user information"

See Management API v2 Docs for more info on allowed attributes for Resource Servers.

Deploy Email Provider

To deploy an email provider, you must create provider.json file under the emails directory of your GitHub repository. Example:


    "name": "smtp",
    "enabled": true,
    "credentials": {
        "smtp_host": "",
        "smtp_port": 25,
        "smtp_user": "smtp_user",
        "smtp_pass": "smtp_secret_password"

See Management API v2 Docs for more info on allowed attributes for Email Provider.

Deploy Email Templates

The supported email templates are:

  • verify_email
  • reset_email
  • welcome_email
  • blocked_account
  • stolen_credentials
  • enrollment_email
  • mfa_oob_code

To deploy an email template, you must create an HTML file under the emails directory of your GitHub repository. For each HTML file, you need to create a JSON file (with the same name) with additional options for that template. For example, to deploy a blocked_account template, you would create two files:



    "template": "blocked_account",
    "from": "",
    "subject": "",
    "resultUrl": "",
    "syntax": "liquid",
    "body": "./blocked_account.html",
    "urlLifetimeInSeconds": 432000,
    "enabled": true

Excluded records

You can exclude the following records from the deployment process: rules, clients, databases, connections and resourceServers. If excluded, the records will not be modified by deployments.

Keywords Mapping

Beginning with version 3.0.0, you can use keywords mapping to manage your secrets and tenant-based environment variables.

There are two ways to use the keyword mappings. You can either wrap the key using @ symbols (e.g., @@key@@), or you can wrap the key using # symbols (e.g., ##key##).

  • If you use @ symbols, your value will be converted from a JavaScript object or value to a JSON string.

  • If you use # symbols, Auth0 will perform a literal replacement.

This is useful for something like specifying different variables across your environments. For example, you could specify different JWT timeouts for your Development, QA/Testing, and Production environments.

Refer to the snippets below for sample implementations:


  "callbacks": [
  "jwt_configuration": {
    "lifetime_in_seconds": ##JWT_TIMEOUT##,
    "secret_encoded": true

Track deployments

To track your deployments, navigate to the extensions page, click on the row for the GitHub Deployments extension, and select the Deployments tab. You will see a list of all deployments, both successful and failed.

Deployments Overview

If a deployment fails, you can examine the details of the deployment to determine why. Details are also available for successful deployments.

Deployment Log

Also, if you configured a Slack Incoming Webhook, you will be notified on Slack if a deployment has succeeded or failed.

Slack Integration