Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 24 additions & 15 deletions docs/batch-changes/configuring-credentials.mdx
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
# Configuring Credentials

<p className="subtitle">
Learn how to configure access tokens for code hosts when creating
changesets.
Learn how to configure credentials for code hosts when creating changesets.
</p>

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.
Expand All @@ -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.

<Callout type="note">
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.
</Callout>

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

Expand All @@ -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.

<Callout type="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.
</Callout>
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

Expand Down