Skip to content

feat: docs for batch spec library and templates #1244

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 7 commits into from
Jul 21, 2025
Merged

feat: docs for batch spec library and templates #1244

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
35f0cfb
doc updates
bahrmichael Jul 7, 2025
5b94cea
update site admin docs
bahrmichael Jul 7, 2025
2a7bf96
wip
bahrmichael Jul 7, 2025
d07d468
some cleanup
bahrmichael Jul 7, 2025
5f3010c
cleanup
bahrmichael Jul 7, 2025
4acbe44
review udpates
bahrmichael Jul 11, 2025
372513f
Merge branch 'main' into bahrmichael/templates-doc-update
bahrmichael Jul 11, 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
77 changes: 66 additions & 11 deletions docs/admin/config/batch_changes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -344,12 +344,37 @@ However, if the user deletion is permanent, deleting both account and data, then

## Batch Spec Library

<Callout type="note"> Batch Spec Library is currently in Experimental.</Callout>
The Batch Spec Library offers curated examples and guided templates that make large-scale code modifications accessible to developers at every skill level. As a site admin you can manage the library.

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.
The library distinguishes between [templates](#templates) and [examples](#library-examples). Examples are batch specs that are meant to be modified by power users who are comfortable with the batch spec syntax. Templates, on the other hand, are batch specs that contain variables that the user can provide data for through form fields without having to modify the batch spec code.

Sourcegraph instances come with a couple of examples out of the box. You can use the GraphQL APIs to [manage the Batch Spec Library](#managing-the-batch-spec-library).

As a site admin, you can [feature records](#featured-records) to highlight the most useful templates and examples for your organization.

### Examples

Examples are complete batch specs intended for advanced users who are comfortable working with YAML and writing code. These examples serve as inspiration and starting points for custom batch changes.

Examples are visible in the library pane when you are in the batch spec editor. They are not displayed by default in the templates list which is the entry point for users creating a batch change. See [choosing a template](/batch-changes/create-a-batch-change#choosing-a-template) for more details.

### Templates

<Callout type="note">Templates are supported in Sourcegraph v6.6 and more.</Callout>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "more" should be "higher" here

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, but it is a common pattern we have across our docs. cc @MaedahBatool

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MaedahBatool is it worth it to replace these instances with "higher"? I sorta feel strongly that "more" is incorrect here (in terms of English).


Templates are like examples, but with variables for easy reuse across multiple batch changes. Templates provide the simplest path for users to create batch changes without needing to learn Batch Spec YAML syntax. Users select from a curated list of templates and complete a form with the required parameters, making batch change creation accessible to all team members regardless of their technical background.

An example becomes a template once it has at least one [variable](#variables) defined. It will then be displayed in the list of templates that a user sees when they click on [create a batch change](/batch-changes/create-a-batch-change).

Variables can be used to replace any text in the batch spec except the batch change's name.

### Managing the Batch Spec Library

<Callout type="note">Site admins can manage the Batch Spec library in Sourcegraph v6.4 and more.</Callout>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"more" --> "higher" IMO


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
Expand All @@ -371,20 +396,15 @@ batchSpecLibrary(first: 100) {
}
```

### Featured Templates

<Callout type="note">Featured templates are supported in Sourcegraph v6.4 and more.</Callout>
### Featured Records

Site-admins can mark a template as featured by either clicking the star button next to the list of library records. Featured records will automatically move to a section atop the remaining library records.
Site-admins can mark a record as featured by either clicking the star button next to the list of library records or adding the `"featured"` [label](#labels) label with a GraphQL mutation. Featured records will automatically move to a section atop the remaining library records.

### Labels

<Callout type="note">Labels are supported in Sourcegraph v6.4 and more.</Callout>
Library records support an optional `labels` field for categorization and filtering.

Batch Spec Library records support an optional `labels` field for categorization and filtering. Common labels include:

- `"featured"` - Marks popular or recommended batch specs that are displayed in a "Featured Templates" section above the remaining examples
- Custom labels for organizational categorization (not exposed to Batch Changes users yet)
The `"featured"` label marks popular or recommended batch specs that are displayed in a featured section above the remaining examples and templates.

To remove the featured status, you can update the library record with an empty list of labels (`[]`).

Expand All @@ -409,3 +429,38 @@ batchSpecLibrary(first: 100, labels: ["featured"]) {
}
}
```

### Variables

<Callout type="note">Variables are supported in Sourcegraph v6.6 and more.</Callout>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"more" --> "higher"


When creating a template, you can define placeholders for values that will vary between different uses of the template. Users filling out the template see these variables as form fields where they can enter specific values like repository names, file paths, or commit messages.

<Callout type="note">You cannot use a variable for the batch change name.</Callout>

The `libraryVariables` field accepts an array of variable objects, each with the following configuration options:

- **Name**: The variable identifier used in the template
- **Display name**: Optional human-readable name shown in the form interface
- **Pattern**: Regular expression for input validation
- **Description**: Help text shown to users explaining what the variable is for
- **Mandatory**: Boolean field indicating whether the variable is required
- **Level**: Validation message severity level (`INFO`, `WARNING`, or `ERROR`)

You can create templates by adding the `libraryVariables` field to the `createBatchSpecLibraryRecord` mutation. Here's an example that creates a simple template:

```graphql
createBatchSpecLibraryRecord(name:"Hello World Template",
libraryVariables: [{
name:"REPOSITORY_QUERY",
displayName:"Repository Search Query",
pattern: ".+",
description:"The search query to find repositories.",
mandatory:true,
level:ERROR
}], spec: "version: 2\nname: hello-world\ndescription: Add Hello World to READMEs\n\non:\n - repositoriesMatchingQuery: $REPOSITORY_QUERY\n\nsteps:\n - run: echo Hello World | tee -a README.md\n container: alpine:3\n\nchangesetTemplate:\n title: Hello World\n body: Add Hello World to README\n branch: hello-world\n commit:\n message: Add Hello World to README") {
id
}
```

To update or remove variables from an existing template, you will need to recreate the record using the `deleteBatchSpecLibraryRecord` and `createBatchSpecLibraryRecord` mutations.
172 changes: 82 additions & 90 deletions docs/batch-changes/create-a-batch-change.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,91 @@

Batch Changes are created by writing a [batch spec](/batch-changes/batch-spec-yaml-reference) and executing that batch spec with the [Sourcegraph CLI](https://github.com/sourcegraph/src-cli) `src`.

There are two ways of creating a batch change:

1. On your Sourcegraph instance, with [server-side execution](#on-your-sourcegraph-instance)
2. On your local machine, with the [Sourcegraph CLI](#using-the-sourcegraph-cli)

## On your Sourcegraph instance

Here, you'll learn how to create and run a batch change via server-side execution.

To get started, click the **Batch Changes** icon in the top navigation or navigate to `/batch-changes`.

### Create a batch change

Click the **Create batch change** button on the Batch Changes page, or go to `/batch-changes/create`.

![create_batch_change_button](https://sourcegraphstatic.com/docs/images/batch_changes/2025/create_batch_change_button.png)

You will be redirected to a page showing you a list of curated templates.

### Choosing a template

<Callout type="info">Templates is a feature available in Sourcegraph 6.6 and later.</Callout>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we replace "more" with "higher" earlier on, just make sure to replace this "later" with "higher" too (or just replace all the instances of "more" with "later" to be consistent)


From the template selection page, you can either:

- **Pick a template** from the list of curated templates that best matches your use case
- **Click "Start from Scratch"** if you prefer to continue without a template

![templates_list](https://sourcegraphstatic.com/docs/images/batch_changes/2025/templates_list.png)

Your site admin can curate the list of available templates to match your organization's specific needs and use cases.

### Filling out template fields

If you selected a template, you will need to fill out the form fields specific to that template. These fields will customize the batch spec to your specific requirements.

![templates_form](https://sourcegraphstatic.com/docs/images/batch_changes/2025/templates_form.png)

The form fields are validated by regular expressions. If the validation fails, look at the description of that field to see what kind of value is required.

### Choose a name for your batch change

After you've filled out the template form fields, or after you've clicked "Start from Scratch", you will be prompted to choose a name for your namespace and optionally define a custom namespace to put your batch change in.

![server-side-batch-change](https://sourcegraphstatic.com/docs/images/batch_changes/2024/create-a-batch-change.png)

Once done, click **Create**.

### Previewing batch spec and workspaces

You can now see the batch spec and run a preview of the affected repositories and workspaces from the right-hand side panel. After resolution, it will show all the workspaces in repositories that match the given `on` statements. You can search through them and determine if your query is satisfying before starting execution. You can also exclude single workspaces from this list.

Batch Changes can also be used on [multiple projects within a monorepo](/batch-changes/creating-changesets-per-project-in-monorepos) by using the `workspaces` key in your batch spec.

There are two ways of creating a batch change:
The library contains examples that you can apply right into your batch spec if you need inspiration. Your site admin can manage the library of examples.

![ssbc_workspace_preview](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_workspace_preview.png)

### Executing your batch spec

When the spec is ready to run, ensure the [preview](/batch-changes/create-a-batch-change#previewing-workspaces) is up to date and then click **Run batch spec**. This takes you to the execution screen. On this page, you see:

- Run statistics at the top
- All the workspaces, including status and diff stat, in the left panel
- Details on a particular workspace on the right-hand side panel where you can see steps with:
- Logs
- Results
- Command
- Per-step diffs
- Output variables
- Execution timelines for debugging

Once finished, you can proceed to the batch spec preview, as you know it from before.

![ssbc_execution_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_execution_screen.png)

1. On your local machine, with the [Sourcegraph CLI](#create-a-batch-change-with-the-sourcegraph-cli)
2. Remotely, with [server-side execution](/batch-changes/server-side)
### Previewing and applying the batch spec

On this page, you can review the proposed changes. Once satisfied, click **Apply**.

## Create a batch change with the Sourcegraph CLI
Congratulations, you ran your first batch change server-side 🎊

![ssbc_preview_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_preview_screen.png)

## Using the Sourcegraph CLI

This part of the guide will walk you through creating a batch change on your local machine with the Sourcegraph CLI.

Expand Down Expand Up @@ -83,7 +160,7 @@ src batch preview -f YOUR_BATCH_SPEC.yaml

After you've applied a batch spec, you can [publish changesets](/batch-changes/publishing-changesets) to the code host when you're ready. This will turn the patches into commits, branches, and changesets (such as GitHub pull requests) for others to review and merge.

You can share the link to your batch change with other users if you want their help. Any user on your Sourcegraph instance can [view it in the batch changes list](/batch-changes/create-a-batch-change#viewing-batch-changes).
You can share the link to your batch change with other users if you want their help. Any user on your Sourcegraph instance can [view it in the batch changes list](/batch-changes/view-batch-changes).

If a user viewing the batch change lacks read access to a repository in the batch change, they can only see [limited information about the changes to that repository](/batch-changes/permissions-in-batch-changes#repository-permissions-for-batch-changes) (and not the repository name, file paths, or diff).

Expand Down Expand Up @@ -114,88 +191,3 @@ src batch preview -f your_batch_spec.yaml -namespace <SOURCEGRAPH_USERNAME_OR_OR
```

When creating a batch change server-side using the UI, you can select the namespace to which the batch change belongs when you create it.

### Administration

Once a batch change is open, any Sourcegraph user can view it. However, the namespace determines who can administer it, such as editing or deleting it. When a batch change is created in a user namespace, only that user (and site admins) can administer it. When a batch change is created in an organization namespace, all members of that organization (and site admins) can administer it.

## Create a batch change with server-side execution

Here, you'll learn how to create and run a batch change via server-side execution.

Click the **Create batch change** button on the Batch Changes page, or go to `/batch-changes/create`.
You will be prompted to choose a name for your namespace and optionally define a custom namespace to put your batch change in.

![server-side-batch-change](https://sourcegraphstatic.com/docs/images/batch_changes/2024/create-a-batch-change.png)

Once done, click **Create**.

### Editing the spec file

You should see the editor view now. This view consists of three main areas:

- The library sidebar panel on the left
- The editor in the middle
- The workspaces preview panel on the right

![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. 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

Once satisfied or to test your batch change's scope, you can run a new preview from the right-hand side panel at any time. After resolution, it will show all the workspaces in repositories that match the given `on` statements. You can search through them and determine if your query is satisfying before starting execution. You can also exclude single workspaces from this list.

![ssbc_workspace_preview](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_workspace_preview.png)

### Executing your batch spec

When the spec is ready to run, ensure the preview is up to date and then click **Run batch spec**. This takes you to the execution screen. On this page, you see:

- Run statistics at the top
- All the workspaces, including status and diff stat, in the left panel
- Details on a particular workspace on the right-hand side panel where you can see steps with:
- Logs
- Results
- Command
- Per-step diffs
- Output variables
- Execution timelines for debugging

Once finished, you can proceed to the batch spec preview, as you know it from before.

![ssbc_execution_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_execution_screen.png)

### Previewing and applying the batch spec

On this page, you can review the proposed changes and the operations taken by Sourcegraph on each changeset. Once satisfied, click **Apply**.

Congratulations, you ran your first batch change server-side 🎊

![ssbc_preview_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_preview_screen.png)

## Viewing batch changes

You can view a list by clicking the **Batch Changes** icon in the top navigation bar:

![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.

![use-filters-batch-changes](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering.png)

## Filtering changesets

When looking at a batch change, you can search and filter the list of changesets with the controls at the top of the list:

![filter-changesets](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering_changesets.png)
33 changes: 33 additions & 0 deletions docs/batch-changes/view-batch-changes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Viewing Batch Changes

<p className="subtitle">Learn how to view, search, and filter your Batch Changes.</p>

## Viewing batch changes

You can view a list of Batch Changes by clicking the **Batch Changes** icon in the top navigation bar:

![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 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 filters to switch between showing all open or closed Batch Changes.

![use-filters-batch-changes](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering.png)

## Filtering changesets

When looking at a batch change, you can search and filter the list of changesets with the controls at the top of the list:

![filter-changesets](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering_changesets.png)

## Administration

Once a batch change is open, any Sourcegraph user can view it. However, the namespace determines who can administer it, such as editing or deleting it. When a batch change is created in a user namespace, only that user (and site admins) can administer it. When a batch change is created in an organization namespace, all members of that organization (and site admins) can administer it.
24 changes: 16 additions & 8 deletions src/data/navigation.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -286,19 +286,27 @@ export const navigation: NavigationItem[] = [
href: '/batch-changes/create-a-batch-change',
subsections: [
{
title: 'Update a Batch Change',
href: '/batch-changes/update-a-batch-change'
title: 'Sourcegraph UI',
href: '/batch-changes/create-a-batch-change#on-your-sourcegraph-instance'
},
{
title: 'Close a Batch Change',
href: '/batch-changes/delete-a-batch-change'
},
{
title: 'Run Server Side',
href: '/batch-changes/server-side'
title: 'Sourcegraph CLI',
href: '/batch-changes/create-a-batch-change#using-the-sourcegraph-cli'
}
]
},
{
title: 'View Batch Changes',
href: '/batch-changes/view-batch-changes'
},
{
title: 'Update a Batch Change',
href: '/batch-changes/update-a-batch-change'
},
{
title: 'Close a Batch Change',
href: '/batch-changes/delete-a-batch-change'
},
{
title: 'Bulk Operations',
href: '/batch-changes/bulk-operations-on-changesets',
Expand Down