Skip to content
Merged
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
13 changes: 8 additions & 5 deletions docs/batch-changes/configuring-credentials.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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** |
| ---------------------------------------------------------------------------- | :----------------------------------------------: | :------------------------------------------------------------: |
Expand Down Expand Up @@ -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.

Expand All @@ -220,6 +221,8 @@ Adding a GitHub app is done through the Batch Changes section of your user setti
<source src="https://sourcegraphstatic.com/docs/videos/batch_changes/2024/batches-github-app-create.mp4" type="video/mp4" />
</video>

<Callout type="info">It may take a few seconds before Sourcegraph receives the callback from GitHub. Please refresh your page until you see a success message.</Callout>

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
Expand Down
Loading