diff --git a/docs/batch-changes/configuring-credentials.mdx b/docs/batch-changes/configuring-credentials.mdx index e455ce5bc..2fa691269 100644 --- a/docs/batch-changes/configuring-credentials.mdx +++ b/docs/batch-changes/configuring-credentials.mdx @@ -15,14 +15,14 @@ Batch Changes can use access tokens for all code hosts, and [GitHub apps (experi 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 +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](/batch-changes/tracking-existing-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 +- 🟒 **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. | **Operation** | **User Credential** | **Global Service Credential** | | ---------------------------------------------------------------------------- | :----------------------------------------------: | :------------------------------------------------------------: | @@ -200,12 +200,13 @@ GitHub apps follow the same concepts as [personal and global access tokens](#typ - 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](https://docs.github.com/en/rest/repos/forks?apiVersion=2022-11-28#create-a-fork)). +- 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 (e.g. organization). +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. @@ -220,6 +221,8 @@ Adding a GitHub app is done through the Batch Changes section of your user setti +It may take a few seconds before Sourcegraph receives the callback from GitHub. Please refresh your page until you see a success message. + 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