Managing source control connections in Gearset

To run a comparison in Gearset, you need to add a source and target location of your metadata. Gearset supports comparing and deploying metadata that is source controlled, with support for any git-based source control provider.

You can add connections via OAuth to the following providers, whether they are hosted on the cloud:

• GitHub

• Bitbucket (also known as Bitbucket Cloud)

• GitLab

• Azure DevOps Git

• AWS CodeCommit

Or hosted on-premise by your company:

• GitHub Enterprise

• Bitbucket Server

• GitLab (self-managed)

You can also connect to any git-based source control system using a username/password. This includes Google Cloud Source Repositories, which can also be authenticated in this way. Note that, if you’re using Google Cloud Source Repositories, you need at least one branch in your repository before Gearset can authenticate against it.

Adding a source control connection via OAuth

1. Under My connections on the left-hand side menu, click on Source control and services

2. Click + Connect to next to the required source control provider

3. Log in to your cloud git provider account

4. When prompted by your git provider, grant Gearset access to the repository

When connecting to GitLab, for example, click Authorize to grant Gearset access, then follow the default OAuth authentication flow.

Adding a source control connection via username/password

Custom git connections can be added with the instructions below, but note that, in this way, only one single repository is available (as opposed to all the repositories, using the OAuth method).

1. Under My connections on the left-hand side menu, click on Source control and services

2. Scroll down to the Custom git repositories section, and click on ADD NEW CUSTOM GIT REPOSITORY... 

3. Enter your username and password, and specify the URL for the repository

4. Optionally, click Test connection to confirm that Gearset can access your repository

5. Click Add repository to save the connection

   

Your connection will now be listed on the Source control and services page.

Note:

1. If your account uses 2FA, you may need to create a custom application password (also known as personal access token) for Gearset to connect to your repository.

2. For GitHub with HTTPS as the authentication type you will need to enter a personal access token in place of a password, as described here.

3. If you are using the SSH Authentication type and a non-default port (22) is used, you may need to format the repo address with a ssh:// prefix.

This git repository will now appear under Source control > Custom Git when you compare metadata.

Note: If you are using a GitLab repository as a target of a deployment, you will need to add it as a custom git connection first. This is due to a GitLab limitation that does not allow applications to use OAuth tokens as credentials in a git push.

Viewing and deleting saved source control connections

All of the source control connections you have added to Gearset can be seen in the My connections section, on the Source control and services page.

To remove a saved connection, click the bin icon under the Actions column.

Changing the source control authentication username

If you'd like to update a saved connection to a new username (e.g. update your GitHub user that is linked to Gearset), you'll need to remove the connection and clear your cache before adding the new username. 

You can clear you cache by either: 

• Logging out of your source control account via their web UI (e.g. log out of Github.com); or 

• Opening a new incognito or private tab of your browser to add the new connection; or

• Revoking the OAuth token in the original source control connection

If you don't clear the cached connection, Gearset may re-use the previously saved connection in your browser.