Docs working branch for Sourcegraph version 6.2 (#1044)

Docs for SG 6.2 release.

---------

Co-authored-by: Michael Bahr <[email protected]>
Co-authored-by: sourcegraph-bot-devx <[email protected]>
Co-authored-by: Jacob Pleiness <[email protected]>
Co-authored-by: Jacob Pleiness <[email protected]>

Author: 4 people

README.md

@@ -1,6 +1,6 @@
 # Sourcegraph Docs
 
-<!-- Working branch for FEB 2025 Release -->
+<!-- Working branch for April 2025 Release -->
 
 Welcome to the Sourcegraph documentation! We're excited to have you contribute to our docs. We've recently rearchitectured our docs tech stack — powered by Next.js, TailwindCSS and deployed on Vercel. This guide will walk you through the process of contributing to our documentation using the new tech stack.
 

docs.config.js

@@ -1,5 +1,5 @@
 const config = {
-	DOCS_LATEST_VERSION: '6.1'
+	DOCS_LATEST_VERSION: '6.2'
 };
 
 module.exports = config;

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,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.
 
@@ -306,3 +341,32 @@ When a user is deleted, their Batch Changes become inaccessible in the UI but th
 This allows recovering the Batch Changes if the user is restored.
 
 However, if the user deletion is permanent, deleting both account and data, then the associated Batch Changes are also permanently deleted from the database. This frees storage space and removes dangling references.
+
+## Batch Spec Library
+
+<Callout type="note"> Batch Spec Library is currently in Experimental.</Callout>
+
+The Batch Spec Library is a collection of Batch Specs that can be used to create Batch Changes. Sourcegraph provides a few Batch Specs out of the box.
+
+Site admins can manage the library through the GraphQL mutations `createBatchSpecLibraryRecord`, `updateBatchSpecLibraryRecord`, and `deleteBatchSpecLibraryRecord`. Use the query `batchSpecLibrary` to list all available Batch Spec examples.
+
+```graphql
+createBatchSpecLibraryRecord(name: "example", spec: "version: 2\nname: example") {
+  id
+}
+
+updateBatchSpecLibraryRecord(id: "QmF0Y2hTcGVjTGlicmFyeVJlY29yZDo4", name: "example-2", spec: "version: 2\nname: example-2") {
+  id
+}
+
+deleteBatchSpecLibraryRecord(id: "QmF0Y2hTcGVjTGlicmFyeVJlY29yZDo4") {
+  alwaysNil
+}
+
+batchSpecLibrary(first: 100) {
+  nodes {
+    id
+    name
+  }
+}
+```

docs/batch-changes/configuring-credentials.mdx

@@ -101,13 +101,70 @@ Let's learn how you can do it for different code hosts.
 
 ### GitHub
 
-On GitHub.com, [create a personal access token (classic) with the correct scopes](https://github.com/settings/tokens/new?scopes=repo,read:org,user:email,read:discussion,workflow).
+On GitHub.com, create a personal access token or fine-grained access token with the correct scopes.
 
 The `workflow` scope is technically only required if your batch changes modify files in the `.github` directory of a repository. Still, it's recommended to enable it regardless to avoid confusing errors at a later time.
 
 When working with organizations that have SAML SSO (Single Sign On) enabled, configuring credentials requires an additional step that [involves white-listing the token for use in that organization](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on).
 
-<Callout type="info">At present, only classic personal access tokens (PATs) are supported. Alternative token types like OAuth access tokens (e.g., OAuth apps), and fine-grained personal access tokens (PATv2) are not supported.</Callout>
+<Callout type="info">Currently, classic and fine-grained access tokens are supported only. Alternative token types like OAuth access tokens (for example, OAuth apps) are not supported.</Callout>
+
+#### Personal Access Token
+
+Personal access tokens will have access to all repositories you have access to.
+
+[Click here to prefill the form](https://github.com/settings/tokens/new?scopes=repo,read:org,user:email,read:discussion,workflow).
+
+Required Scopes:
+
+- `repo`
+- `read:org`
+- `user:email`
+- `read:discussion`
+- `workflow`
+
+#### Fine-Grained Access Token
+
+Fine-grained access tokens allow more granular control of what actions can be performed for a given set of repositories. Most notably, fine-grained access tokens don't grant access by default to all repositories you have access to.
+
+In contrast to personal access tokens, fine-grained access tokens for organization resources may be restricted, may have an expiration, and may require approval.
+
+- **Restriction**: If an administrator of your GitHub organization has restricted access via fine-grained access tokens, you may not be able to use them for Batch Changes
+- **Expiration**: If your organization has configured fine-grained access tokens to have maximum lifetimes, you may need to recreate the token when it has expired
+- **Approval**: If your organization has configured fine-grained access tokens to require approval, you may need to wait for an administrator to approve the token before you can use it with Batch Changes
+
+Start by navigating to create a [new fine-grained access token](https://github.com/settings/personal-access-tokens/new).
+
+Pick the resource owner that owns the repositories you want to use with Batch Changes. This will likely be your company's GitHub organization.
+
+![Select resource owner for fine-grained access token](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/fine_grained_select_owner.png)
+
+Scroll down and select "All repositories" so that your token can access all current and future repositories that you have access to. You may restrict it to "Only select repositories", but you may have to generate a new token when you want to handle a new repository with Batch Changes.
+
+![Select all repositories for repository access](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/fine_grained_select_repos.png)
+
+Under "Permissions," click on the arrows on the right-hand side to expand the list of repository and organization permissions.
+
+![Expand the repository permissions by clicking on the arrows](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/fine_grained_expand_permissions.png)
+
+Under "Repository permissions", select the following permissions:
+
+- Contents: Read and write
+- Metadata: Read-only
+- Pull requests: Read and write
+- Workflows: Read and write
+
+Under "Organization permissions", select the following permissions:
+
+- Custom properties: Read-only
+
+Once you created the token, copy it and add it to your Batch Changes credentials.
+
+![Add credential modal with fine-grained token selected](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/setup_fine_grained_access_token.png)
+
+If your organization requires approval for fine-grained access tokens, you must wait for an administrator to approve the token before you can publish changesets with it.
+
+The fine-grained access token is now ready to use. Create a new batch change to start using it.
 
 ### GitHub Enterprise
 
@@ -129,7 +186,7 @@ When working with organizations that have SAML SSO (Single Sign On) enabled, con
 
 <Callout type="warning">Currently, for customers on an instance of GitHub Enterprise Cloud that uses [SSH certificate authorities](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities) and requires SSH certificates to authenticate, we are unable to provide a means of authenticating Batch Changes to your code host.</Callout>
 
-<Callout type="info">At present, only classic personal access tokens (PATs) are supported. Alternative token types like OAuth access tokens (e.g. OAuth apps), and fine-grained personal access tokens (PATv2) are not supported.</Callout>
+<Callout type="info">Currently, classic personal and fine-grained access tokens are supported only. Alternative token types like OAuth access tokens (for example, OAuth apps) are not supported.</Callout>
 
 ### GitLab
 
@@ -239,4 +296,4 @@ To remove a GitHub app from your Sourcegraph instance, navigate back to the same
   <source src="https://sourcegraphstatic.com/docs/videos/batch_changes/2024/batches-github-app-delete.mp4" type="video/mp4" />
 </video>
 
-If you want to delete the GitHub app entirely you have to navigate to [GitHub's list of applications](https://github.com/settings/apps/), and delete it from there.
+If you want to delete the GitHub app entirely, you have to navigate to [GitHub's list of applications](https://github.com/settings/apps/) and delete it from there.

docs/batch-changes/create-a-batch-change.mdx

@@ -140,7 +140,7 @@ You should see the editor view now. This view consists of three main areas:
 
 ![ssbc_editor_panels](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_editor_panels.png)
 
-You can pick from the examples in the library pane to get started quickly or begin working on your batch spec in the editor right away. The editor will provide documentation as you hover over tokens in the YAML spec and supports auto-completion.
+You can pick from the examples in the library pane to get started quickly or begin working on your batch spec in the editor right away. Site admins can configure the examples. The editor will provide documentation as you hover over tokens in the YAML spec and supports auto-completion.
 
 ### Previewing workspaces
 
@@ -180,6 +180,14 @@ You can view a list by clicking the **Batch Changes** icon in the top navigation
 
 ![batch-change-icon-to-view](https://sourcegraphstatic.com/docs/images/batch_changes/2024/batch_changes_icon_in_menu.png)
 
+### Title-based search
+
+You can search through your previously created batch changes by title. This search experience makes it much easier to find the batch change you’re looking for, especially when you have large volumes of batch changes to monitor.
+
+Start typing the keywords that match the batch change’s title, and you will see a list of relevant results.
+
+![title-based-search-batch-changes](https://storage.googleapis.com/sourcegraph-assets/Docs/title-based-search-bc.png)
+
 ## Filtering Batch Changes
 
 You can also use the filters to switch between showing all open or closed Batch Changes.

docs/batch-changes/rebasing-changesets.mdx

@@ -0,0 +1,36 @@
+# Rebasing changesets
+
+<p className="subtitle">Learn how to rebase your existing changesets.</p>
+
+<Callout type="note">This feature is supported for Sourcegraph versions 6.2 or more.</Callout>
+
+If your codehost requires changesets to be up to date with the main branch, you can use the rebase functionality of the Web UI to update the changesets.
+
+<Callout type="warning">Rebasing does not resolve merge conflicts.</Callout>
+
+## Requirements
+
+- Sourcegraph instance with repositories in it. See the [Quickstart](/#quick-install) guide on how to set up a Sourcegraph instance
+- A [global service account token](/batch-changes/configuring-credentials#global-service-account-tokens) for Batch Changes (**a personal access token cannot currently be used for importing changesets**)
+
+## Select changesets to rebase
+
+After navigating to the changesets of your batch change, select one or more **published** changesets to rebase. You can only rebase changesets after they have been published to the codehost.
+
+![List of changesets with two of them selected](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/rebase_changesets.png)
+
+If a changeset is already up to date with the main branch, rebasing will result in no changes.
+
+## Start the rebase bulk operation
+
+With all applicable changesets selected, click the **Select action** button, and then select **Rebase changesets**.
+
+![List of changesets and dropdown overlay](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/rebase_dropdown.png)
+
+Confirm the popup to start the rebase bulk operation.
+
+![Popup to confirm rebase action](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/rebase_confirm.png)
+
+You can see the progress of the rebase operation in the **Bulk Actions** tab.
+
+![List of bulk operations showing that rebase has completed](https://storage.googleapis.com/sourcegraph-assets/docs/images/batch_changes/2025/rebase_status.png)

docs/batch-changes/site-admin-configuration.mdx

@@ -17,6 +17,7 @@ Using Batch Changes requires a [code host connection](/admin/external_services/)
   - [Outgoing webhooks](/admin/config/webhooks/outgoing), which publish events related to batch changes and changesets to enable deeper integrations with your other tools and systems
   - [Auto-delete branch on merge/close](/admin/config/batch_changes#automatically-delete-branches-on-merge-close), which automatically deletes branches created by Batch Changes when changesets are merged or closed
   - [Commit signing for GitHub](/admin/config/batch_changes#commit-signing-for-github), which signs commits created by Batch Changes via a GitHub App (Beta)
+  - [Batch spec library](/admin/config/batch_changes#batch-spec-library), which help your users write batch specs and follow best practices
 
 ## Disable Batch Changes