Configure Source Control with Bitbucket

Learn how to set up Source Control with Bitbucket.

You can use Source Control with Bitbucket Cloud to manage changes with pull requests.

note

Retool does not support self-hosted Bitbucket Data Center instances.

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

Create an access token for the repository

1. Create a Bitbucket access token for the repository.
2. Under Scopes > Repositories, select Read, Write, Admin, and Delete. This gives the access token the ability to access and modify the repository containing your Retool apps.

Configure Bitbucket repository settings

Go to the Source Control settings, and select Set up Bitbucket. Enter the following settings.

Setting	Description	Example
Bitbucket Workspace	The name of the workspace you created for the Retool repository. This variable is case-sensitive.	retool-workspace
Bitbucket Repository	The repo name in step 2.	retool-apps
Bitbucket Branch	Retool automatically tracks changes to this branch	main
Bitbucket URL	The domain used to access your self-hosted Bitbucket instance.	https://bitbucket.org/
Bitbucket Enterprise API URL	The REST API route for your self-hosted Bitbucket instance. Defaults to https://api.bitbucket.org/2.0.	https://api.bitbucket.org/2.0
Bitbucket Access Token	The access token you created.	loDJlwRetoolTYXOFbO

Configure Bitbucket settings on Retool

Secure credential management

The Bitbucket Access Token field supports embedded expressions for secure credential management.

Toggle the Template variables in Source Control config feature flag in Settings > Beta to enable this feature.

• You can reference configuration variables:

  {{ environment.variables.MY_KEY_OR_TOKEN }}

• On self-hosted instances, you can also reference secrets from secrets managers:

  {{ secrets.MY_SECRET.KEY }}

The UI includes autocomplete and validation to help you use embedded expressions correctly.

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.