From dc30d679ed5343712765a1f23bdb66fc85dafe44 Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Mon, 10 Mar 2025 13:23:00 +0100 Subject: [PATCH 1/4] feat: update docs for commit signing --- docs/admin/config/batch_changes.mdx | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/admin/config/batch_changes.mdx b/docs/admin/config/batch_changes.mdx index 0da626424..5f06029d2 100644 --- a/docs/admin/config/batch_changes.mdx +++ b/docs/admin/config/batch_changes.mdx @@ -180,7 +180,31 @@ 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 + +Batch Changes supports Commit Signing with GitHub Apps since version 5.1 and with SSH Keys since version 6.2. + +### Commit signing with SSH Keys (GitLab and GitHub) + + This feature is supported only in Sourcegraph versions 6.2 or more. + +Commit signing with SSH keys can only be used in combination with a personal access token. + +Sourcegraph can be configured to sign commits using SSH keys, both with user and site admin credentials. + +To enable **commit signing for your Batch Changes user**, navigate to **Settings > Batch Changes** and click on "Add credentials" for a GitHub or GitLab code host. + +If you already have a credential for the given code host, you have to remove it first. + +Enter your personal access token, and check the box "Sign commits on this code host". This will add an additional step to the setup flow. Click on "Add credential" and wait for Batch Changes to verify the access token. + +Once the credential is added, you can continue to the "Get Commit Signing Key" step to get the public SSH key that Batch Changes will use to sign commits. You can view the public key at any time by clicking on "View Credentials". + +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. + +To enable **commit signing as a site admin**, navigate to **Site Admin > Section: Batch Changes > Settings** and click on "Add credentials" for a GitHub or GitLab code host. The rest of the setup is the same as above. + +### Commit signing with GitHub Apps The feature is currently in Beta stage and supported on Sourcegraph versions 5.1 or more. From f083e3828d494eb2c751fddbcf38560694998d16 Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Thu, 13 Mar 2025 12:06:42 +0100 Subject: [PATCH 2/4] add pictures --- docs/admin/config/batch_changes.mdx | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/admin/config/batch_changes.mdx b/docs/admin/config/batch_changes.mdx index 5f06029d2..1d6657797 100644 --- a/docs/admin/config/batch_changes.mdx +++ b/docs/admin/config/batch_changes.mdx @@ -194,16 +194,27 @@ Sourcegraph can be configured to sign commits using SSH keys, both with user and To enable **commit signing for your Batch Changes user**, navigate to **Settings > Batch Changes** and click on "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, you have to remove it first. -Enter your personal access token, and check the box "Sign commits on this code host". This will add an additional step to the setup flow. Click on "Add credential" and wait for Batch Changes to verify the access token. +Enter your personal access token, and check the box "Sign commits on this code host". This will add an additional step to the setup flow. Click on "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 that Batch Changes will use to sign commits. You can view the public key at any time by clicking on "View Credentials". -Once the credential is added, you can continue to the "Get Commit Signing Key" step to get the public SSH key that Batch Changes will use to sign commits. You can view the public key at any time by clicking on "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 on "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 The feature is currently in Beta stage and supported on Sourcegraph versions 5.1 or more. From a2e3c55d71a6477aa6458ea98aa9fd0cd3975b32 Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Wed, 19 Mar 2025 11:02:50 +0100 Subject: [PATCH 3/4] include fine-grained access token --- docs/admin/config/batch_changes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/config/batch_changes.mdx b/docs/admin/config/batch_changes.mdx index 1d6657797..7316cb618 100644 --- a/docs/admin/config/batch_changes.mdx +++ b/docs/admin/config/batch_changes.mdx @@ -188,7 +188,7 @@ Batch Changes supports Commit Signing with GitHub Apps since version 5.1 and wit This feature is supported only in Sourcegraph versions 6.2 or more. -Commit signing with SSH keys can only be used in combination with a personal access token. +Commit signing with SSH keys can only be used in combination with a personal access token or fine-grained access token. Sourcegraph can be configured to sign commits using SSH keys, both with user and site admin credentials. From 82d76cb9337073c5fd43529626ee41a1e40421e5 Mon Sep 17 00:00:00 2001 From: Maedah Batool Date: Tue, 25 Mar 2025 13:09:45 -0700 Subject: [PATCH 4/4] Add feedback --- docs/admin/config/batch_changes.mdx | 48 ++++++++++++++--------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/admin/config/batch_changes.mdx b/docs/admin/config/batch_changes.mdx index 7316cb618..197f3a7d3 100644 --- a/docs/admin/config/batch_changes.mdx +++ b/docs/admin/config/batch_changes.mdx @@ -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 @@ -171,38 +171,38 @@ 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 -Batch Changes supports Commit Signing with GitHub Apps since version 5.1 and with SSH Keys since version 6.2. +Batch Changes supports commit signing with both GitHub apps and with SSH keys. -### Commit signing with SSH Keys (GitLab and GitHub) +### Commit signing with SSH keys (GitLab and GitHub) - This feature is supported only in Sourcegraph versions 6.2 or more. +Commit signing with SSH keys is currently Experimental and is supported only with Sourcegraph v6.2 or more. -Commit signing with SSH keys can only be used in combination with a personal access token or fine-grained access token. +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, both with user and site admin credentials. +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 on "Add credentials" for a GitHub or GitLab code host. +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, you have to remove it first. +If you already have a credential for the given code host, remove it first. -Enter your personal access token, and check the box "Sign commits on this code host". This will add an additional step to the setup flow. Click on "Next" and wait for Batch Changes to verify the access token. +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 that Batch Changes will use to sign commits. You can view the public key at any time by clicking on "View Credentials". +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) @@ -211,13 +211,13 @@ 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 on "Add credentials" for a GitHub or GitLab code host. The rest of the setup is the same as above. +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 +### Commit signing with GitHub apps - The feature is currently in Beta stage and supported on Sourcegraph versions 5.1 or more. +Commit signing with GitHub apps is currently in Beta and is supported with Sourcegraph v5.1 or more. 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.