Skip to main content

Configure Source Control with Bitbucket

caution

Source Control with Bitbucket is available on on-premise deployments of Self-hosted Retool v2.105 or later.

With Source Control with Bitbucket, you can use pull requests on Bitbucket cloud to manage changes to your Retool applications.

Setup instructions​

Disable git syncing​

If you've enabled Git Syncing, disable it:

  • In your docker.env file, set DISABLE_GIT_SYNCING=true and VERSION_CONTROL_LOCKED=false.
  • In the Settings > Advanced tab in Retool, remove the repository URL and branch name from your Git Syncing configuration.

Prerequisites​

This guide requires access to a Bitbucket account with permissions to create workspaces and repositories.

1. Create a Bitbucket app password​

  1. Create a Bitbucket app password.
  2. On the app password page under Permissions > Repositories, select Read, Admin, and Delete. This gives the app password the ability to access and modify the repository containing your Retool apps.

2. Create a new Bitbucket workspace and repository​

  1. Create a Bitbucket workspace for your Retool repository.
  2. Create a Git repository in Bitbucket for your Retool apps.

Create a new Bitbucket repository

3. Set up environment variables on your Retool instance​

Set the following environment variables on your Retool instance on the api and jobs-runner containers.

VariableDescriptionExample
BITBUCKET_USERThe Bitbucket usernameretool
BITBUCKET_APP_PASSWORDThe app password you generated in step 1loDJlwRetoolTYXOFbO
BITBUCKET_WORKSPACEThe workspace name in step 2. This variable is case-sensitive.retool-space
BITBUCKET_REPOThe repo name in step 2retool-apps
BITBUCKET_MAIN_BRANCHRetool automatically tracks changes to this branchmain

If you use your own SSL certificates, set the SSL_CERT_FILE and NODE_EXTRA_CA_CERTS environment variables on the jobs-runner and api containers to the path to your SSL certificate.

note

In Retool v2.113 or later, you can configure all environment variables except BITBUCKET_APP_PASSWORD by navigating to Settings > Source Control. Retool saves all required environment variables if they are set.

4. Test your configuration​

After you set up your environment variables, if you’re an admin on your Retool instance, you can visit Settings > Source Control.

If your Bitbucket environment is correctly configured, the page will show your Bitbucket commits in the Deployment Dashboard section. You can also click the Test connection button, which sends a request to test the connection.

Deployment dashboard and test connection example

If you don't see the Deployment Dashboard and your Bitbucket commits on Settings > Source Control, check that your environment variables are correctly configured.

What's next?​

You are now ready to use source control. Learn how to create branches, pull requests, merging changes, and use other source control features in the getting started guide.