Skip to content

feat: update docs for commit signing #1021

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 25, 2025
Merged

feat: update docs for commit signing #1021

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
dc30d67
feat: update docs for commit signing
bahrmichael Mar 10, 2025
f083e38
add pictures
bahrmichael Mar 13, 2025
5a65ffc
Merge branch 'main' into bahrmichael/commit-signing
bahrmichael Mar 13, 2025
a2e3c55
include fine-grained access token
bahrmichael Mar 19, 2025
82d76cb
Add feedback
MaedahBatool Mar 25, 2025
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
63 changes: 49 additions & 14 deletions docs/admin/config/batch_changes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,11 @@ To restore the default behavior, you can either delete the `batchChanges.rollout

Or, to put it another way:

| `batchChanges.rolloutWindows` configuration | Behavior |
|---------------------------------------------|-----------|
| Omitted, or set to `null` | Changesets will be reconciled as fast as the code host allows; essentially the same as setting a single `{"rate": "unlimited"}` window. |
| `batchChanges.rolloutWindows` configuration | Behavior |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Omitted, or set to `null` | Changesets will be reconciled as fast as the code host allows; essentially the same as setting a single `{"rate": "unlimited"}` window. |
| Set to an array (even if empty) | Changesets will be reconciled using the rate limit in the current window using [the leaky bucket behavior described below](#leaky-bucket-rate-limiting). If no window covers the current period, then no changesets will be reconciled until a window with a non-zero [`rate`](#rate) opens. |
| Any other value | The configuration is invalid, and an error will appear. |
| Any other value | The configuration is invalid, and an error will appear. |

#### Leaky bucket rate limiting

Expand Down Expand Up @@ -171,18 +171,53 @@ For those that require a separate API call, Batch Changes will only be able to d

Refer to the table below to see the levels with which each code host is supported:

Code Host | Changeset property or separate API call? | Support on merge | Support on close | Note
--------- | --------- | :-: | :-: | ----
Azure DevOps | Changeset property | ✓ | ✗ |
Bitbucket Cloud | Changeset property | ✓ | ✓ |
Bitbucket Server | API call | ✓ | ✓ |
GitHub | API call | ✓ | ✓ |
GitLab | Changeset property | ✓ | ✓ |
Gerrit | API call | ✗ | ✓ | Requires ["delete own changes" permission](https://gerrit-review.googlesource.com/Documentation/access-control.html#category_delete_own_changes) at minimum
Code Host | Changeset property or separate API call? | Support on merge | Support on close | Note
---------------- | ---------------------------------------- | :--------------: | :--------------: | -----------------------------------------------------------------------------------------------------------------------------------------------------------
Azure DevOps | Changeset property | ✓ | ✗ |
Bitbucket Cloud | Changeset property | ✓ | ✓ |
Bitbucket Server | API call | ✓ | ✓ |
GitHub | API call | ✓ | ✓ |
GitLab | Changeset property | ✓ | ✓ |
Gerrit | API call | ✗ | ✓ | Requires ["delete own changes" permission](https://gerrit-review.googlesource.com/Documentation/access-control.html#category_delete_own_changes) at minimum

## Commit signing for GitHub
## Commit signing

<Callout type="note"> The feature is currently in Beta stage and supported on Sourcegraph versions 5.1 or more.</Callout>
Batch Changes supports commit signing with both GitHub apps and with SSH keys.

### Commit signing with SSH keys (GitLab and GitHub)

<Callout type="note">Commit signing with SSH keys is currently Experimental and is supported only with Sourcegraph v6.2 or more.</Callout>

Commit signing with SSH keys can only be combined with a personal or fine-grained access token.

Sourcegraph can be configured to sign commits using SSH keys with user and site admin credentials.

To enable **commit signing for your Batch Changes user**, navigate to **Settings > Batch Changes** and click **Add credentials** for a GitHub or GitLab code host.

![List of code hosts with an arrow pointing to add credential](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/code_host_add_credential.png)

If you already have a credential for the given code host, remove it first.

Enter your personal access token, and check the "Sign commits on this code host" box. This will add a step to the setup flow. Click "Next" and wait for Batch Changes to verify the access token.

![The modal for adding a credential with an arrow pointing to the checkbox for commit signing](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/setup_commit_signing_checkbox.png)

Once the credential is added, you can copy the public SSH key Batch Changes will use to sign commits. You can view the public key anytime by clicking **View Credentials**.

![The modal displays the ssh key used for commit signing](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/setup_commit_signing_view_ssh_key.png)

Add this public SSH key to your [GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) or [GitLab](https://docs.gitlab.com/user/ssh/#add-an-ssh-key-to-your-gitlab-account) account.
Make sure you add it as a signing key.

![Add the key to your code host as a signing key](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/github_add_signing_key.png)

To enable **commit signing as a site admin**, navigate to **Site Admin > Section: Batch Changes > Settings** and click **Add credentials** for a GitHub or GitLab code host. The rest of the setup is the same as above.

![Site admin settings for batch changes](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/batch_changes_site_admin_settings.png)

### Commit signing with GitHub apps

<Callout type="note">Commit signing with GitHub apps is currently in Beta and is supported with Sourcegraph v5.1 or more.</Callout>

Sourcegraph can be configured to [sign commits pushed to GitHub](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification) using a GitHub App. Commit signing prevents tampering by unauthorized parties and provides a way to ensure that commits pushed to branches created by Batch Changes actually do come from Sourcegraph. Enabling commit signing for Batch Changes can also help pass checks in build systems or CI/CD pipelines that require that all commits are signed and verified before they can be merged.

Expand Down