configuring_credentials.md

Configuring credentials

NOTE: This page describes functionality added in Sourcegraph 3.22. Older Sourcegraph versions only allow batch changes to be applied and managed by site admins.

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 three 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 (Admins only) - A token that can be used by any Batch Changes user who does not have a personal access token configured.
3. Sourcegraph code host connection token (Admins only) - A token that is typically set when connecting Sourcegraph to a code host for the first time and is used across the entire Sourcegraph instance. Using the code host connection token with Batch Changes will be deprecated in the future.

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	Code Host Connection 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.

WARNING: Using the code host connection token with Batch Changes will be deprecated in the future; therefore, we highly recommend that admins configure a global service account token for Batch Changes instead.

Personal access tokens

Do I need to add a personal access token?

Personal access tokens are not 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.

NOTE: Commit author is determined by your spec file or local git config at the time of running src batch [apply|preview], completely independent from code host credentials.

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

NOTE: This section describes functionality added in Sourcegraph 3.27, and which is only accessible to site administrators.

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.

Sourcegraph also uses the global service account to track existing changesets and keep changesets up to date. If no global service account token is set, we can currently fall back to the token configured for the code host connection. However, this fallback will be deprecated in the future, so for this reason we highly recommend setting up a global service account.

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 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 the site admin area, then click Remove. The code host's indicator should revert to the empty red circle once the token is removed.

Code host connection tokens

WARNING: Using code host connection tokens with Batch Changes will be deprecated and removed in future versions of Sourcegraph.

Code host connection tokens are typically configured the first time a site administrator is connecting Sourcegraph to the external code host. Within Batch Changes, they are only used for syncing and importing changesets when a global service account token is not configured.

NOTE: Prior to Sourcegraph 3.29, admin users were also able to use the code host connection token as a fallback for other Batch Changes operations, such as creating and updating changesets. However, non-admin users were unable to apply batch changes without another form of access token being configured.

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

Follow the steps to create a personal access token on GitHub. 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:

NOTE: workflow 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.

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

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 hosts SSH access settings page.