Configuring credentials

Interacting with a code host (such as creating, updating, or syncing changesets) is made possible by configuring an access token for that code host. Sourcegraph uses these tokens to manage changesets on your behalf, and with your specific permissions.

Requirements

• Sourcegraph instance with repositories in it. See the "Quickstart" guide on how to setup a Sourcegraph instance.
• Account on the code host with access to the repositories you wish to target with your batch changes.

Types of access tokens used by Batch Changes

There are two types of access token that can be configured for use with Batch Changes:

1. Personal access token - A token set by an individual Batch Changes user for their personal code host user account.
2. Global service account token (Configurable by admins only) - A token that can be used by any Batch Changes user who does not have a personal access token configured. These are also required for importing changesets and syncing changeset state from the code host when webhooks are not configured. Although currently importing changesets is not supported without a global access token, if you’re concerned about individual user permissions, we would not advise using a global access token.

Different tokens are used for different types of operations, as is illustrated in the hierarchy table below.

🟢 Preferred - Sourcegraph will prefer to use this token for this operation, if it is configured.

🟡 Fallback - Sourcegraph will fall back to use this token for this operation, if it is configured.

🔴 Unsupported - Sourcegraph cannot use this token for this operation.

Operation	Personal Access Token	Global Service Account Token
Pushing a branch with the changes	🟢	🟡
Publishing a changeset	🟢	🟡
Updating a changeset	🟢	🟡
Closing a changeset	🟢	🟡
Importing a changeset	🔴	🟢
Syncing a changeset	🔴	🟢

When writing a changeset to the code host, the author will reflect the token used (e.g., on GitHub, the pull request author will be you). It is for this reason that a personal access token is preferred for most operations.

Personal access tokens

Do I need to add a personal access token?

Personal access tokens are not strictly required if a global access token has also been configured, but users should add one if they want Sourcegraph to create changesets under their name.

Adding a token

Adding a personal access token is done through the Batch Changes section of your user settings:

1. From any Sourcegraph page, click on your avatar at the top right of the page.
2. Select Settings from the dropdown menu.
3. Click Batch Changes on the sidebar menu.
4. Click Add credentials and follow the steps to create a new token for the code host

Code hosts with tokens configured are indicated by a green tick to the left of the code host name, while code hosts without tokens have an empty red circle next to them.

Removing a token

To remove a token, navigate back to the same section of your user settings, then click Remove:

The code host's indicator should revert to the empty red circle once the token is removed.

Global service account tokens

Do I need to add a global service account token?

Global credentials are usable by all users of the Sourcegraph instance who have not added their own personal access tokens for Batch Changes. This makes them a handy fallback, but not strictly required if users are adding their own tokens for publishing changesets.

However, currently a global service account token is required for importing existing changesets on your code hosts into batch changes.

Additionally, if you have not configured webhooks from your code host, Sourcegraph requires a global service account keep changesets up to date.

If forks are enabled, then note that repositories will also be forked into the service account.

Adding a token

Adding a global service account token is done through the Batch Changes section of the site admin area:

1. From any Sourcegraph page, click on your avatar at the top right of the page.
2. Select Site admin from the dropdown menu.
3. Click Settings under the Batch Changes sub-heading on the sidebar menu.
4. Click Add credentials and follow the steps to create a new token for the code host

Code hosts with tokens configured are indicated by a green tick to the left of the code host name, while code hosts without tokens have an empty red circle next to them.

Removing a token

To remove a token, navigate back to the same section of the site admin area, then click Remove. The code host's indicator should revert to the empty red circle once the token is removed.

Creating a code host token

To finish configuring the new credentials, you will need to create a new personal access token on your code host and paste it into the input field on the Add credentials modal:

GitHub

GitHub.com

On GitHub.com, create a personal access token (classic) with the correct scopes.

The workflow scope is technically only required if your batch changes modify files in the .github directory of a repository, but we recommend enabling it regardless to avoid confusing errors at a later time.

When working with organizations that have SAML SSO (Single Sign On) enabled, configuring credentials requires an additional step that involves white-listing the token for use in that organization.

GitHub Enterprise

Follow the steps to create a personal access token (classic) on GitHub Enterprise. Batch Changes requires the following scopes:

• repo
• read:org
• user:email
• read:discussion
• workflow

This is done by selecting the relevant checkboxes when creating the token:

The workflow scope is technically only required if your batch changes modify files in the .github directory of a repository, but we recommend enabling it regardless to avoid confusing errors at a later time.

When working with organizations that have SAML SSO (Single Sign On) enabled, configuring credentials requires an additional step that involves white-listing the token for use in that organization.

GitLab

Follow the steps to create a personal access token on GitLab. Batch Changes requires the following scopes:

• api
• read_repository
• write_repository

This is done by selecting the relevant checkboxes when creating the token:

Bitbucket Server / Bitbucket Data Center

Follow the steps to create a personal access token on Bitbucket.

Batch Changes requires the access token to have the write permission on both projects and repositories. This is done by selecting the Write level in the Projects dropdown, and letting it be inherited by repositories:

Bitbucket Cloud

Follow the steps to create an app password on Bitbucket. Batch Changes requires the following scopes:

• account:read
• repo:read
• repo:write
• pr:write
• pipeline:read

Azure DevOps

Follow the steps to create a PAT on Azure DevOps. Batch Changes requires the following scopes:

• Organization:All accessible organizations
• Code:Full
• Code:Status
• Pull Request Thread:Read & Write
• User Profile:Read

Gerrit

• Permissions to create, comment, close, merge, and delete a Change in Gerrit.
• Create an HTTP password in the user settings page.

SSH access to code host

When Sourcegraph is configured to clone repositories using SSH via the gitURLType setting, an SSH keypair will be generated for you and the public key needs to be added to the code host to allow push access. In the process of adding your personal access token you will be given that public key. You can also come back later and copy it to paste it in your code host's SSH access settings page.