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.
In order to publish changesets with Batch Changes, you need to add a personal access token for each code host that your batch change interacts with. These tokens are used by Sourcegraph to create and manage changesets on behalf of yourself, and with your specific permissions, on the code host. Since Sourcegraph 3.27, it is also possible to configure a global service account per code host to be used when the user doesn't have credentials configured.
- Sourcegraph instance with repositories in it. See the "Quickstart" guide on how to setup a Sourcegraph instance.
Access tokens can be configured either for your user account, or globally, if you're a site admin of the Sourcegraph instance.
Adding personal access tokens 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.
You should now see a list of the code hosts that are configured on Sourcegraph. Code hosts with tokens configured are indicated by a green tick, while code hosts without tokens have an empty red circle next to them. If a global access token has been configured, it is not required (but you can still do it, to create the changesets under your name) to do this. The UI will inform you if that's the case.
Configuring a global service account is done through the Batch Changes section of the site admin area: (Site admins only)
- From any Sourcegraph page, click on your avatar at the top right of the page.
- Select Site admin from the dropdown menu.
- Click Batch Changes on the sidebar menu.
You should now see a list of the code hosts that are configured on Sourcegraph. Code hosts with tokens configured are indicated by a green tick, while code hosts without tokens have an empty red circle next to them. Credentials that are configured here will be usable by all users of the Sourcegraph instance for publishing and updating changesets on the code host.
To add a token for a code host, click on the Add token button next to its name. This will display an input modal like the following:
To create a personal access token for a specific code host provider, please refer to the relevant section for "GitHub", "GitLab", or "Bitbucket Server". Once you have a token, you should paste it into the Sourcegraph input shown above, and click Add token.
NOTE: See "Code host interactions in Batch Changes" for details on what the permissions are used for.
Once this is done, Sourcegraph should indicate that you have a token with a green tick:
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.
In addition to the below, you should refer to GitHub's documentation on creating a personal access token.
Sourcegraph requires the repo, read:org, user:email, and read:discussion scopes to be enabled on the user token. This is done by selecting the relevant checkboxes when creating the token:
In addition to the below, you should refer to GitLab's documentation on creating a personal access token.
Sourcegraph requires the api, read_repository, and write_repository scopes to be enabled on the user token. This is done by selecting the relevant checkboxes when creating the token:
In addition to the below, you should refer to Bitbucket Server's documentation on creating a personal access token.
Sourcegraph 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:
Removing personal access tokens is done through the the Batch Changes section of your user settings. To access this page, follow these instructions (also shown in the video below):
- 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.
You should now see a list of the code hosts that are configured on Sourcegraph. Code hosts with tokens configured are indicated by a green tick, while code hosts without tokens have an empty red circle next to them.
To remove a personal access token for a code host, click Remove next to that code host. The code host's indicator will change to an empty red circle to indicate that no token is configured for that code host:
