Skip to main content
Batch Changes lets you make automated code changes at scale — across hundreds or thousands of repositories — and track every resulting pull request or merge request until it is merged. You define what changes to make using a YAML spec file, preview the results before publishing, and monitor the status of every changeset from a single dashboard.
Batch Changes is available on Enterprise plans.

​
Key concepts

TermDescription
Batch changeA named group of related code changes, with a title, description, and associated changesets
Batch specA YAML file that defines the batch change: which repositories to target, what commands to run, and how to template the resulting commits and changesets
ChangesetA pull request, merge request, or equivalent reviewable change on a code host, created by a batch change
Published changesetA changeset that has been pushed to the code host and opened as a pull request or merge request
Unpublished changesetA preview visible in the Sourcegraph UI that has not yet been pushed to the code host
Changeset specA record describing the diff, commit message, branch, title, and body for one changeset in one repository — produced by executing the batch spec

​
Supported code hosts

A single batch change can span multiple repositories across multiple code hosts:
  • GitHub pull requests
  • GitLab merge requests
  • Bitbucket Server / Data Center pull requests
  • Bitbucket Cloud pull requests
  • Gerrit changes
  • Perforce changelists (Beta)

​
Quickstart

This walkthrough creates a batch change that appends “Hello World” to every README file across your repositories.

​
Prerequisites

  • A Sourcegraph instance with repositories
    • The Sourcegraph CLI (src) installed and authenticated (download from your Sourcegraph instance at /.api/src-cli/)
1

Install the Sourcegraph CLI

Install the src binary that matches your Sourcegraph instance version.
curl -L https://<YOUR-SOURCEGRAPH-INSTANCE-URL>/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src
chmod +x /usr/local/bin/src
Authenticate the CLI with your instance:
src login https://<YOUR-SOURCEGRAPH-INSTANCE-URL>
2

Write a batch spec

A batch spec is a YAML file that describes your intent. Save the following as hello-world.batch.yaml:
version: 2
name: hello-world
description: Add Hello World to READMEs

# Find all repositories that contain a README file.
on:
  - repositoriesMatchingQuery: file:README

# In each repository, run this command. Each repository's resulting diff is captured.
steps:
  - run: IFS=$'\n'; echo Hello World | tee -a $(find -name README)
    container: alpine:3

# Describe the changeset you want for each repository.
changesetTemplate:
  title: Hello World
  body: My first batch change!
  branch: hello-world
  commit:
    message: Append Hello World to all README files
The on section selects repositories using a Sourcegraph search query. The steps section defines commands to run in each repository using a Docker container. The changesetTemplate defines the branch name, commit message, and pull request metadata.
3

Preview the batch change

Run the preview command to compute the changes without touching any repositories:
src batch preview -f hello-world.batch.yaml
When the command finishes, it prints a link to the preview page in Sourcegraph. Open the link to review every diff before anything is published.
4

Apply the batch change

On the preview page, verify the diffs look correct. Click Apply to create the batch change.The changesets are now created in Sourcegraph but are unpublished — nothing has been pushed to your code host yet. This lets you review and selectively publish only the changesets you are ready for.
5

Configure code host credentials

Before publishing, Sourcegraph needs permission to open pull requests on your behalf. Add a personal access token for each code host under your user settings, or ask your site administrator to configure global service account tokens.This is a one-time setup — you do not need to repeat it for every batch change.
6

Publish changesets to the code host

From the batch change page, select the changesets you want to publish and choose Publish changesets from the actions dropdown.Sourcegraph will push the branch and open the pull request or merge request on the code host. You can publish as a draft if the code host supports it.

​
Publishing and tracking changesets

After a batch change is created, the dashboard shows the status of every changeset:
  • Status: Open, merged, or closed
  • Checks: CI results (passed, failed, or pending)
  • Review status: Approved, changes requested, or pending
The burndown chart shows the proportion of changesets that have been merged over time, giving you a clear view of overall progress.
You can re-run src batch preview with an updated spec at any time. Sourcegraph will show you a diff of what will change — including which existing changesets will be updated or archived.

​
Server-side vs local execution

Batch changes can be executed directly on your Sourcegraph instance without requiring the src CLI on your local machine. This is useful for large batch changes that would be slow to run locally, or for running batch changes in CI pipelines.To run a batch change server-side, use the Sourcegraph web UI to upload your batch spec and trigger execution. You can monitor progress and review diffs without any local setup.
Server-side execution requires your Sourcegraph instance to be configured with executors. Ask your site administrator to set this up.

​
Common use cases

Upgrade dependencies

Bump a library version in package.json, go.mod, or requirements.txt across every affected repository in one operation.

Patch security vulnerabilities

Apply a critical security fix to all repositories that use a vulnerable dependency, and track every PR until merged.

Migrate deprecated APIs

Replace calls to a deprecated library function with the new API across hundreds of repositories at once.

Enforce linting standards

Run a linter with auto-fix across your codebase and open PRs for repositories that have violations.

Standardize configuration

Update CI pipeline files, Dockerfiles, or deployment manifests to conform to a new organizational standard.

Track manual changesets

Import and track existing pull requests that were created outside of Batch Changes to get a unified view of a migration effort.

Code Search

Use Code Search to find repositories and write the repositoriesMatchingQuery clauses in your batch spec.

Code Insights

Track the progress of a migration over time using Code Insights after running Batch Changes.

Deep Search

Use Deep Search to understand the codebase before writing the batch spec commands.

Admin overview

Configure executors for server-side batch change execution and manage code host credentials.

Build docs developers (and LLMs) love

Get started for freeTalk to us