Connect your app to GitHub
The Bitbucket Deployments extension allows you to deploy rules, rules configs, connections, database connection scripts, clients, client grants, resource servers, Universal Login pages and email templates from Bitbucket to Auth0. You can configure a Bitbucket repository, keep all of your Rules and Database Connection scripts there, and have them automatically deployed to Auth0 whenever you push changes to your repository.
1. Add a new application
Configure the Extension
To install and configure this extension, click on the Bitbucket Deployments box in the list of provided extensions on the Extensions page of the Auth0 Management Dashboard. The Install Extension window will open.
Set the following configuration variables:
- REPOSITORY: The repository from which you want to deploy your Rules and Database Connection scripts. This can be either a public or private repository
- BRANCH: The branch the extension will monitor for changes
- USER: The username used to access the Bitbucket account. Make sure you use the username, and not the email
- PASSWORD: The user password or an app password you create through the Bitbucket settings to grant permissions to certain apps (
Repositories: Readpermission is required)
- 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: The Webhook URL for Slack used to notify you of successful and failed deployments
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 Bitbucket Deployments extension. The first time you click on your installed extension, you will be asked to grant it to access your Bitbucket account. Once you agree, you will be directed to the Bitbucket Integration page.
The Configuration page will display the Payload URL you will need to create a webhook to your Bitbucket repository pointing to the extension.
Copy and paste this value into the Add Webhook page for your Bitbucket Repository.
2. Register your new app
Once you have set up the webhook in Bitbucket using the provided information, you are ready to start committing to your repository.
With each commit you push to your configured Bitbucket repository, the webhook will call the extension to initiate a deployment if changes were made to one of these folders:
The Deploy button on the Deployments tab of the extension allows you to manually deploy the Rules and Database Connection scripts that you already have in your Bitbucket repository. This is useful if your repository already contains items 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.
To maintain a consistent state, the extension will always do a full deployment 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.
3. Get your GitHub app's Client ID and Client Secret
Deploy Database Connection Scripts
To deploy Database Connection scripts, you must first create a directory under
database-connections. The name of the directory must match exactly the name of your database connection in Auth0. You can create as many directories as you have Database Connections.
Under the created directory, create one file for each script you want to use. The allowed scripts are:
For a generic Custom Database Connection, only the
login.js script is required. If you enable the migration feature, you will also need to provide the
You can find examples in the Auth0 Samples repository. While the samples were authored for GitHub, it will work for a Bitbucket integration as well.
4. Copy your GitHub app's Client ID and Client Secret
Deploy Database Connection Settings
To deploy Database Connection settings, you must create
This will work only for Auth0 connections (strategy === auth0); for non-Auth0 connections use
See Management API v2 Docs for more info on allowed attributes for Connections.
5. Access GitHub API
To deploy a connection, you must create a JSON file under the
connections directory of your Bitbucket repository. Example:
This will work only for non-Auth0 connections (
strategy !== auth0); for Auth0 connections, use
For more info on the allowed attributes for connections, see the [Post Connections endpoint] (/api/management/v2#!/Connections/post_connections).
Deploy Universal Login Pages
The supported pages are:
To deploy a page, you must create an HTML file under the
pages directory of your Bitbucket 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:
For example, if you create the file
rules/set-country.js, the extension will create a Rule in Auth0 with the name
You can control the Rule order and status (
You can find a
login_success example in the Auth0 Samples repository. While the sample was authored for GitHub, it will work for a Bitbucket integration as well.
Set Rule Order
To avoid conflicts, you cannot set multiple Rules of the same order. However, you can create a JSON file for each rule, and within each file, assign a value for
order. We suggest using number values that allow for reordering with less risk of conflict. For example, assign a value of
10 to the first Rule and
20 to the second Rule, rather than using values of
Deploy Rules Configs
To deploy a rule config, you must create a JSON file under the
rules-configs directory of your Bitbucket repository. Example:
To deploy a client, you must create a JSON file under the
clients directory of your Bitbucket repository. Example:
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
Deploy Resource Servers
To deploy a resource server, you must create a JSON file under the
resource-servers directory of your Bitbucket repository. Example:
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 Bitbucket repository. Example:
See Management API v2 Docs for more info on allowed attributes for Email Provider.
Deploy Email Templates
The supported email templates are:
To deploy an email template, you must create an HTML file under the
emails directory of your Bitbucket 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:
You can exclude the following records from the deployment process:
resourceServers. If excluded, the records will not be modified by deployments.
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.,
If you use
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:
To track your deployments, navigate to the Extensions page, click on the row for the Bitbucket Deployments extension, and select the Deployments tab. You will see a list of all deployments.
If a deployment fails, you can examine the details of the deployment to determine why. Details are also available for successful deployments.
If you configured a Slack Incoming Webhook, you will be notified on Slack anytime a deployment occurs.