Bitbucket Deployments
The Bitbucket Deployments extension allows you to deploy rules, rule configs, hooks, 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.
Install the extension
To install this extension:
Navigate to the Extensions page of the Auth0 Dashboard, and click the Bitbucket Deployments box. The Install Extension window opens.
Set the following configuration parameters:
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, not the email.
PASSWORD: The user password or an app password you create through the Bitbucket settings to grant permissions to certain apps (
Repositories: Read
permission is required).BASE_DIR: The base directory where all your tenant settings are stored.
AUTO_REDEPLOY: When enabled, the extension redeploys the last successful configuration in the event of a deployment failure. Manual deployments and validation errors do not trigger auto-redeployment.
AUTH0_ALLOW_DELETE: When enabled, the extension is allowed to delete objects that do not exist within the repository.
SLACK_INCOMING_WEBHOOK_URL: The specific Slack webhook to which you want to send reports from the extension.
After you provide this information, click Install.
Because the extension will communicate with your Bitbucket account on your behalf, you will need to authorize its access.
To authorize the extension:
If you're following this guide, you should already be on the Installed Extensions view of the Extensions page of the Auth0 Dashboard. Click Bitbucket Deployments to launch the extension. A consent dialog will appear, requesting access to your Bitbucket account.
Consent to allow the extension to access your Bitbucket account. After you consent, the extension launches, and you are redirected to the Bitbucket Integration page.
Configure the extension
After the extension is installed, you should configure the extension settings. To configure the extension:
If you're following this guide, you should already have launched the extension and been redirected to the Bitbucket Integration page. Click the Configuration tab.
Copy the Payload URL displayed on this page.
To create a webhook from your Bitbucket repository pointing to this extension, you must paste this URL into the Add Webhook page for your Bitbucket repository. To learn more, see Atlassian's Manage Bitbucket Webhooks documentation.
Deployment
Once you have set up the webhook in Bitbucket, 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, which will initiate a deployment if changes were made to one of these folders:
clients
grants
emails
resource-servers
connections
database-connections
rules-configs
rules
pages
To manually deploy the Rules and Database Connection scripts that you already have in your Bitbucket repository, use the Deploy button on the Deployments tab of the extension. This is useful if your repository already contains items that you want to deploy after 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.
Deploy connections
To deploy a connection, create a JSON file under the connections
directory in your Bitbucket repository. For example:
facebook.json
{
"name": "facebook",
"strategy": "facebook",
"enabled_clients": [
"my-client"
],
"options": {}
}
To learn more about the allowed attributes for connections, see Auth0's Management API Post Connections endpoint.
Deploy database connections
To deploy a database connection, create a subdirectory named [connection-name]
under the database-connections
directory in your Bitbucket repository. The name of the subdirectory must exactly match the name of your database connection in Auth0. You can create as many subdirectories as you have database connections.
Create a JSON file named database.json
under the corresponding database-connections/[connection-name]
subdirectory in your Bitbucket repository.
To learn more about allowed attributes for connections, see Auth0's Management API Patch Connections by ID endpoint.
Deploy database connection scripts
To deploy a database connection script, create a JavaScript file under the corresponding database-connections/[connection-name]
subdirectory in your Bitbucket repository. The filename of the JavaScript file should correspond to the database connection script you want to deploy.
Allowed scripts include:
get_user.js
create.js
verify.js
login.js
change_password.js
delete.js
For a generic custom database connection, only the login.js
script is required. However, if you enable the migration feature, you will also need to provide the get_user.js
script.
To see examples, visit the Auth0 Samples GitHub repository. While the samples were authored for GitHub, they will work for a Bitbucket integration too.
Deploy Universal Login pages
Supported pages include:
error_page
guardian_multifactor
login
password_reset
To deploy a page, create an HTML file under the pages
directory in your Bitbucket repository. For each HTML page, you must also create a JSON file (with the same name) that controls whether the page is enabled or disabled.
For example, to deploy a password_reset
page, you would create two files:
your-bitbucket-repo/pages/password_reset.html
your-bitbucket-repo/pages/password_reset.json
To enable the page, the password_reset.json
would contain the following:
{
"enabled": true
}
Deploy rules
To deploy a rule, create a JavaScript file under the rules
directory in your Bitbucket repository. Each rule must be contained in its own JavaScript file. For each JavaScript file, you must also create a JSON file (with the same name) that controls the rule order, status, and stage during which the rule executes.
For example, to deploy a set-country
rule, you would create two files:
your-bitbucket-repo/rules/set-country.js
your-bitbucket-repo/rules/set-country.json
set-country.js
function (user, context, callback) {
if (context.request.geoip) {
user.country = context.request.geoip.country_name;
}
callback(null, user, context);
}
set-country.json
{
"enabled": false,
"order": 15,
"stage": "login_success"
}
To see an example for the login_success
stage, visit the Auth0 Samples GitHub repository. While the sample was authored for GitHub, it will work for a Bitbucket integration too.
Set rule order
To avoid conflicts, multiple rules with the same order are not allowed. 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 1
and 2
, respectively.
Set rule stage
Once you deploy a rule, you cannot change the stage during which the rule executes.If you need the rule to execute during a different stage, you must create a new rule configured for that stage and delete the original rule.
Deploy rule configs
To deploy a rule config, create a JSON file under the rules-configs
directory in your Bitbucket repository. For example:
secret_number.json
{
"key": "secret_number",
"value": 42
}
Deploy clients
To deploy a client, create a JSON file under the clients
directory in your Bitbucket repository. For example:
my-client.json
{
"name": "my-client"
}
To learn more about allowed attributes for clients and client grants, see Auth0's Management API Post Clients endpoint.
Deploy client grants
To specify the client grants for each client, create a JSON file under the grants
directory in your Bitbucket repository. For example:
my-client-api.json
{
"client_id": "my-client",
"audience": "https://myapp.com/api/v1",
"scope": [
"read:users"
]
}
Deploy resource servers
To deploy a resource server, create a JSON file under the resource-servers
directory in your Bitbucket repository. For example:
my-api.json
{
"name": "my-api",
"identifier": "https://myapp.com/api/v1",
"scopes": [
{
"value": "read:users",
"description": "Allows getting user information"
}
]
}
To learn more about allowed attributes for resource servers, see Auth0's Management API Post Resource Servers endpoint.
Deploy email providers
To deploy an email provider, create a provider.json
file under the emails
directory in your Bitbucket repository. For example:
provider.json
{
"name": "smtp",
"enabled": true,
"credentials": {
"smtp_host": "smtp.server.com",
"smtp_port": 25,
"smtp_user": "smtp_user",
"smtp_pass": "smtp_secret_password"
}
}
To learn more about allowed attributes for email providers, see Auth0's Management API Patch Provider endpoint.
Deploy email templates
Supported email templates include:
verify_email
reset_email
welcome_email
blocked_account
stolen_credentials
enrollment_email
mfa_oob_code
To deploy an email template, create an HTML file under the emails
directory in your Bitbucket repository. For each HTML file, you must also create a JSON file (with the same name) that contains additional options for that template.
For example, to deploy a blocked_account
template, you would create two files:
your-bitbucket-repo/emails/blocked_account.html
your-bitbucket-repo/emails/blocked_account.json
blocked_account.json
{
"template": "blocked_account",
"from": "",
"subject": "",
"resultUrl": "",
"syntax": "liquid",
"body": "./blocked_account.html",
"urlLifetimeInSeconds": 432000,
"enabled": true
}
Exclude records
You can exclude the following records from the deployment process:
rules
clients
databases
connections
resourceServers
If excluded, records will not be modified by deployments.

Keyword mappings
Beginning with version 3.0.0, you can manage your secrets and tenant-based environment variables using keyword mappings. This is useful if you want to specify different variables across your environments. For example, you could specify different JWT timeouts for your Development, QA/Testing, and Production environments.
To use keyword mappings, either wrap the key using:
@
symbols (e.g.,@@key@@
), which will cause your value to be converted from a Javascript object or value to a JSON string.#
symbols (e.g.,##key##
), which will cause Auth0 to perform a literal replacement.
A sample implementation is as follows:
Client.json
{
...
"callbacks": [
"##ENVIRONMENT_URL##/auth/callback"
],
"jwt_configuration": {
"lifetime_in_seconds": ##JWT_TIMEOUT##,
"secret_encoded": true
}
...
}

Track deployments
To track deployments:
Navigate to the Extensions page of the Auth0 Dashboard, and click Installed Extensions.
Select Bitbucket Deployments, and click the Deployments tab. You will see a list of all deployments, both successful and failed.
You can view more detail by clicking on a deployment.

If you configured a Slack Incoming Webhook, you will also be notified on Slack when deployments succeed or fail.