diff --git a/docs/batch-changes/configuring-credentials.mdx b/docs/batch-changes/configuring-credentials.mdx index 684245b12..996ec5c48 100644 --- a/docs/batch-changes/configuring-credentials.mdx +++ b/docs/batch-changes/configuring-credentials.mdx @@ -1,8 +1,7 @@ # Configuring Credentials

- Learn how to configure access tokens for code hosts when creating - changesets. + Learn how to configure credentials 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. @@ -12,14 +11,30 @@ Interacting with a code host (such as creating, updating, or syncing changesets) - Sourcegraph instance with repositories in it. Read more in the [Quickstart](/batch-changes/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 +## Supported authentication methods + +The following authentication methods are supported: -Batch Changes can use access tokens for all code hosts, and [GitHub apps (experimental)](#github-apps) for GitHub code hosts. +| **Code Host** | **Personal Access Token** | **Fine-Grained Access Token** | **GitHub App** | **OAuth** | +| -------------------------------- | :-----------------------: | :---------------------------: | :------------: | :-------: | +| GitHub | ✅ | ✅ | ✅ (experimental) | ❌ | +| GitHub Enterprise | ✅ | ✅ | ✅ (experimental) | ❌ | +| GitLab | ✅ | ❌ | ❌ | ✅ | +| Bitbucket Server / Data Center | ✅ | ❌ | ❌ | ✅ | +| Bitbucket Cloud | ✅ | ❌ | ❌ | ✅ | +| Azure DevOps | ✅ | ❌ | ❌ | ❌ | +| Gerrit | ✅ | ❌ | ❌ | ❌ | -Two types of credentials can be configured to use with Batch Changes: +## Types of credentials used by Batch Changes + +Credentials can be configured at two levels: 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. +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. If you’re concerned about individual user permissions, using a global credential is not recommended. + + + A global credential is required for [importing changesets](/batch-changes/tracking-existing-changesets) and is used as a fallback for syncing imported changeset state when webhooks are not configured. + Different credentials are used for different types of operations, as shown in the table below. @@ -33,20 +48,14 @@ Different credentials are used for different types of operations, as shown in th | Publishing a changeset | 🟢 | 🟡 | | Updating a changeset | 🟢 | 🟡 | | Closing a changeset | 🟢 | 🟡 | +| Syncing a changeset | 🟢 | 🟡 | | Importing a changeset | 🔴 | 🟢 | -| Syncing a changeset | 🔴 | 🟢 | -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. +The credential used determines who appears as the pull request or merge request author on the code host. This is separate from the git commit author, which is set by the batch spec or local `git config` when running `src batch [apply|preview]`. ## 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. - - - 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. - +Personal access tokens are not strictly required if a global credential has also been configured, but users should add one if they want changesets to be created under their name on the code host. ### Adding personal access token