Configuring Credentials

Learn how to configure access tokens for code hosts when creating changesets.

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

Requirements

• Sourcegraph instance with repositories in it. Read more in the Quickstart guide on how to set up a Sourcegraph instance.
• Account on the code host with access to the repositories you wish to target with your batch changes.

Types of credentials used by Batch Changes

Batch Changes can use access tokens for all code hosts, and GitHub apps (experimental) for GitHub code hosts.

Two types of credentials can be configured to use with Batch Changes:

1. User Credential - A credential set by an individual Batch Changes user for their personal code host user account.
2. Global Service Credential (Configurable by admins only) - A credential that can be used by any Batch Changes user who does not have a personal credential 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 credential, if you’re concerned about individual user permissions, using a global credential is not recommended.

Different credentials are used for different types of operations, as shown in the table below.

• 🟢 Preferred: Sourcegraph will prefer to use this credential for this operation if it is configured.
• 🟡 Fallback: Sourcegraph will fall back to use this credential for this operation if it is configured.
• 🔴 Unsupported: Sourcegraph cannot use this credential for this operation.

When creating a changeset on a code host, the author of the changeset will reflect the credential used (e.g., on GitHub, the user will be the pull request author). This is why a user credential is preferred for most operations.

Personal access tokens

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 personal access token

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

• From any Sourcegraph page, click on your avatar at the top right of the page
• Select Settings from the dropdown menu
• Click Batch Changes on the sidebar menu
• Click Add credentials, and follow the steps to create a new token for the code host. If the code host is GitHub, select Personal Access Token as the Authentication strategy.

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

Removing a personal access token

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

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

Global service account tokens

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 optional if users are adding their own tokens for publishing changesets.

However, a global service account token is currently 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 to keep changesets up to date.

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

Adding a global service token

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

• From any Sourcegraph page, click on your avatar at the top right of the page
• Select Site admin from the dropdown menu
• Click Settings under the Batch Changes sub-heading on the sidebar menu
• Click Add credentials and follow the steps to create a new token for the code host. If the code host is GitHub, select Personal Access Token as the Authentication strategy.

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

Removing a global service token

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

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.

Let's learn how you can do it for different code hosts.

GitHub

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. Still, it's recommended to enable 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 require 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 repositories inherit it:

Bitbucket Cloud

On Bitbucket, follow the steps to create an app password. 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. You will be given that public key when adding your personal access token. You can also come back later and copy and paste it into your code host's SSH access settings page.

GitHub Apps

EXPERIMENTAL: Using GitHub Apps to authenticate Batch Changes is currently experimental, and there may still be some rough edges.

GitHub apps follow the same concepts as personal and global access tokens.

Limitations

• GitHub apps can only be used with GitHub code hosts.
• The forking mechanism (fork:true) is only supported if the GitHub app has access to all repositories of the installation, and if the origin repository and the fork are in the same organization that the GitHub app is installed to (GitHub Docs).
• Your network must allow bidirectional communication between Sourcegraph and GitHub.

Migrating from PATs to GitHub Apps

You can migrate your credentials from PATs to GitHub Apps by deleting the PAT credential and creating a GitHub app credential.

Batch Changes will look at the available credentials, and pick one that matches the targeted namespace (code host, organization, repository).

You can continue to use existing batch changes without modifications.

Adding a GitHub app

Adding a GitHub app is done through the Batch Changes section of your user settings:

• Navigate to the credentials settings, as shown in the personal and global service account token sections
• Click Add credentials, select GitHub App as the Authentication strategy and follow the steps to create a GitHub app

Code hosts with GitHub apps configured are indicated by a green tick to the left of the code host name as well as details about the GitHub app on the right, while code hosts without credentials have an empty red circle next to them.

Updating Installations and Permissions for a GitHub App

Currently, Sourcegraph doesn't handle changed installations or permissions for a GitHub app.

To update those properties, you can delete the current credential and create a new one.

Removing a GitHub app

To remove a GitHub app from your Sourcegraph instance, navigate back to the same section of your settings, then click Remove. Once the GitHub app is removed, the code host's indicator should revert to the empty red circle, unless there's still a global credential configured.

If you want to delete the GitHub app entirely you have to navigate to GitHub's list of applications, and delete it from there.