Skip to main content

Configure Source Control with Azure Repos

Learn how to implement Source Control with Azure Repos.

Source Control Availability
CloudGenerally Available
Self-hosted Edge 3.33 or laterGenerally Available
Self-hosted Stable 3.33 or laterGenerally Available

With Source Control with Azure Repos, you can use pull requests on Azure Repos 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 an Azure DevOps account with permissions to create repos and access tokens.

1. Create a new repository in Azure Repos​

  1. Create or use an existing project under Azure Repos. Ensure its name does not contain any spaces.
  2. Create a new Git repository under Azure Repos for your Retool apps. Ensure that it has a README.md file at the root level directory.

2. Create a personal access token​

  1. Create an Azure Repos personal access token.
  2. Under the Code section, check Full and Status. With this token, Retool will be able to programmatically manipulate your repository, generate pull requests, and see their statuses. Accordingly, use the most appropriate admin in your organization to generate it.

3. Configure Azure repository settings​

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

SettingDescriptionExample
Azure RepositoryThe repo name from step 1. Ensure this name does not contain any spaces.retool-apps
Azure OrganizationThe Azure DevOps organization.acme-co
Azure BranchRetool automatically tracks changes to this branch.main
Azure ProjectThe new or existing Azure DevOps project from step 1. Ensure its name does not contain any spaces.proj-retool
Azure UserThe Azure Repos username.retool
Azure URLYour base Azure URL. For Azure Cloud, this is always http://dev.azure.com. For Azure self-managed, this is the URL where your instance is hosted.https://azure.mycompany.com
Personal Access TokenThe Azure project access tokens to authenticate to the Azure API.AKIAWS3BACWHP6QW6VB2
Use Basic AuthSet this to true if you are using self-hosted Azure Repos.true
Configure Azure Repos settings on Retool
Configure Azure Repos settings on Retool

Secure credential management​

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

This feature is currently rolling to cloud instances and will be available in subsequent edge and stable releases. 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.

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 Azure Repos environment is correctly configured, the page will show your Azure Repos commits in the Deployment Dashboard section. You can also click the Test connection button, which sends a request to test the connection.

If you don't see the Deployment Dashboard and your Azure Repos 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 and pull requests, merge changes, and use other source control features in the getting started guide.