FAQs

Find answers to the most common questions about Batch Changes.

What are the requirements for running Batch Changes?

Batch Changes has specific requirements for running on the Sourcegraph server version, its connected code hosts, and developer environments. Read requirements documentation for more details.

What happens when a user is deleted?

When a user is deleted, their Batch Changes become inaccessible in the UI, but the data is not permanently deleted. This allows the batch changes to be recovered if the user is restored.

You can change the ownership of a batch change before or after soft deletion by using the instructionshere.

However, if the user deletion is permanent (using the "Delete forever" option), 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.

Are there any limitations with the Batch Changes feature?

Code hosts: Batch Changes currently support GitHub, GitLab and Bitbucket Server and Bitbucket Data Center repositories. If you want to use Batch Changes on other code hosts, let us know.
Server-side execution: Batch change steps are run locally (in the Sourcegraph CLI) or server-side Beta. For this reason, the APIs for creating and updating a batch change require you to upload all of the changeset specs (which are produced by executing the batch spec locally). Also, see how scalable Batch Changes.
Multi-user access: It is yet to be possible for multiple users to edit the same batch change that was created under an organization.
It is yet to be possible to reuse a branch in a repository across multiple batch changes.
The only type of user credential supported by Sourcegraph right now is a personal access token, either per user, or via a global service account. Further credential types may be supported in the future.

What happens if my batch change creation breaks down at 900 changesets out of 1,000? Do I have to re-run it?

The default behavior of Batch Changes is to stop creating the diff on repo errors. You can ignore errors by adding the -skip-errors flag to the src batch preview command.

Can I close a batch change and leave the changesets open?

Yes. A confirmation page shows you all the actions that will occur on the various changesets in the batch change after you close it. Open changesets will be marked 'Kept open', meaning batch change won't alter them.

See closing a batch change.

How scalable are Batch Changes? How many changesets can I create?

Batch Changes can create tens of thousands of changesets. This is something we run testing on internally. Some known limitations include:

Since diffs are created locally by running a docker container, performance depends on the capacity of your machine. See How src executes a batch spec
Batch Changes create changesets in parallel locally. You can set up the maximum number of parallel jobs with -j
Manipulating (commenting, notifying users, etc.) changesets at that scale can be clumsy.

How long does it take to create a batch change?

There's a rule of thumb:

Measure the time it takes to run your change container on a typical repository
Multiply by the number of repositories
Divide by the number of changeset creation jobs running in parallel set by the -j CLI flag. It defaults to GOMAXPROCS, roughly the number of available cores

If you run memory-intensive jobs, you might need to reduce the number of parallel job executions. You can run docker stats locally to get an idea of memory usage.

Why does my batch change, not open changesets on all the repositories it should?

Do you have enough permissions? Batch Changes will give you an error on the repositories you cannot access. See Repository permissions for Batch Changes
Does your repositoriesMatchingQuery contain all the necessary flags? If you copied the query from the Sourcegraph UI, note that some flags are represented as buttons (case sensitivity, regex) and do not appear in the query unless you use the copy query button
Are the files you are trying to change in your repository's .gitignore? Batch Changes respects .gitignore files when creating the diff

Can I create tickets or issues along with Batch Changes?

Batch Changes does not support a declarative syntax for issues or tickets. However, steps can run any container. Some users have built scripts to create tickets for each apply:

What happens to the preview page if the batch spec is not applied?

Unapplied batch specs are removed from the database after seven days.

Can I pull containers from private container registries in a batch change?

Yes. When executing a batch spec, src will attempt to pull missing docker images. If you are logged into the private container registry, it will pull from it.

Also, see steps.container. Within the spec, it will work as expected if docker pulls points to your private registry from the command line.

However, outside the spec, src pulls an image from Docker Hub when running in volume workspace mode. This is the default on macOS, so you will need to use one of the following three workarounds:

Run src with the -workspace bind flag. This will be slower but prevent src from pulling the image.
If you have a way of replicating trusted images onto your private registry, you can replicate our image to your private registry. Ensure the replicated image has the same tags, or this will fail.
If you can ad hoc pull images from public Docker Hub, you can run docker pull -a sourcegraph/src-batch-change-volume-workspace to pull the image and its tags.

If you choose to replicate or pull the Docker image, you should ensure that it is frequently synchronized, as a new tag is pushed each time src is released.

What tool can I use for changing or refactoring a `<programming-language>`?

Batch Changes supports any tool that can run in a container and change file contents on a disk. You can use the tool/script that works for your stack or build your own, but here is a list of examples to get started. Common language agnostic starting points:

sed, yq, awk are common utilities for changing text
comby is a language-aware structural code search and replace tool. It can match expressions and function blocks and is great for more complex changes

Why can't I run steps with different container user IDs in the same batch change?

This is an artifact of how Batch Changes executes batch specs. Consider this partial spec:

YAML
steps:
  - run: /do-it.sh
    container: my-alpine-running-as-root
 
  - run: /do-it.sh
    container: my-alpine-running-as-uid-1000
 
  - run: /do-it.sh
    container: my-alpine-running-as-uid-500

Files created by the first step will be owned by UID 0 and (by default) have 0644 permissions, which means that the subsequent steps will be unable to modify or delete those files, as they are running as different, unprivileged users.

Even if the first step is replaced by one that runs as UID 1000, the same scenario will occur when the final step runs as UID 500: files created by the previous steps cannot be modified or deleted.

In theory, it's possible to run the first n steps in a batch spec as an unprivileged user and then run the last n steps as root, but we don't recommend this due to the likelihood that later changes may cause issues. We strongly recommend only using containers that run as the same user in a single batch spec.

How can I use GitHub expression syntax (`${{ }}` literally) in my batch spec?

To tell Sourcegraph not to evaluate ${{ }} like a regular template delimiter, you can quote it and wrap it in a second set of ${{ }} like so:

BASH
${{ "${{ leave me alone! }}" }}

Remember the context in which the inner ${{ }} will be evaluated, and be sure to escape characters as appropriate. Check out the cheat sheet for an example within a shell script.

How is commit author determined for commits produced from Batch Changes?

Commit author is determined when running src batch [apply|preview]. If no author key is defined in the batch spec, src will try to use the git config values for user.name and user.email from your local environment, or batch-changes@sourcegraph.com if no user is set.

Why is the checkbox on my changeset disabled when previewing a batch change?

Since Sourcegraph 3.31, it is possible to publish many types of changesets when previewing a batch change by modifying the publication state for the changeset directly from the UI (see "Publishing changesets"). However, not every changeset can be published by Sourcegraph. By hovering over your changeset's disabled checkbox, you can see why that specific changeset is not currently publishable. The most common reasons include:

The changeset is already published (we cannot unpublish a changeset or convert it back to a draft)
The changeset's publication state is being controlled from your batch spec file (i.e., you have the published flag set in your batch spec); the batch spec takes precedence over the UI
You do not have permission to publish to the repository the changeset would be opened against
The changeset was imported (and was therefore already published by someone or something else)

The changeset may also be in a state that we cannot currently publish from: for example, because a previous push to the code host failed (in which case you should re-apply the batch change), or if you are actively detaching the changeset from your batch change.

Why do my changesets take a long time to sync?

Have you set up webhooks?

Why has my changeset been archived?

When re-running a batch spec on an existing batch change, the scope of repositories affected may change if you modify your on statement or if Sourcegraph finds a different set of results than last time.

If the new batch spec no longer matches a repository for which Sourcegraph has already published a changeset, that changeset will be closed on the codehost and marked as archived in the batch change when you apply the new batch spec.

You can see these actions from the preview screen before you apply the batch spec. Archived changesets are still associated with the batch change but will appear under the "Archived" tab on the batch change page instead.

See how to remove changesets to learn more about archiving changesets, including how to unarchive a changeset and how to remove a changeset from the batch change entirely.

Why is my changeset read-only?

Unmerged changesets on repositories that have been archived on the code host will move into a Read-Only state, which reflects that they cannot be modified any further on the code host. Re-applying the batch change will result in no operations being performed on those changesets, even if they would otherwise be updated. The only exception is those changesets that would be archived due to the on statement or change in search results will still be archived.

If the repository is unarchived, Batch Changes will move the changeset back into its previous state the next time Sourcegraph syncs it.

Why do I get different results count when I run the same search query as a normal search vs. for my `repositoriesMatchingQuery` in a batch spec?

By default, a normal Sourcegraph search will return the total number of matches for a given query, counting matches in the same file or repository as separate results.

However, when you use the search query in your batch spec, the results are grouped based on the repository (or "workspace", if you're working with monorepos) they belong to, giving you the total number of repositories (or workspaces) that match the query. This is because Batch Changes produces one changeset for each matching repository (or workspace).

So, if you have a search query that returns ten results in a single repo, the batch spec will only return one result for that repo. This is the equivalent of supplying the select:repo aggregator parameter to your search query.

Why do I get fewer changes in my changeset diff when I run a batch spec than there are results when I run the same search query?

Sourcegraph search shows you results on any repositories that you have read access to. However, Sourcegraph and Batch Changes need to know which repositories you have write access to.

This disparity most often stems from needing write access to one or more of the repositories where your search query returns results. Consider asking an admin to set up a global service account token if your batch change must update all matching repositories.

Why is my batch change preview hanging?

When working with src, there are occurrences where applying your batch spec might get stuck on a particular step. More so in the Determining workspace type step. The Determining workspace type is a simple step that decides if bind or volume modes should be used based on the command line flags and the OS and architecture.

If volume mode is used (which is default on Mac OS), then src will attempt to pull the sourcegraph/src-batch-change-volume-workspace Docker image from the docker hub since that's required for the batch spec to be executed. The "hanging" is typically caused by the local machine's CLI state. Restarting your computer and applying the batch spec again should fix this.

Can I create a batch change and use a team's namespace so that the team owns the batch change?

Yes, you can create a batch change under a team's namespace so that the team owns and manages the batch change. Here are the steps to achieve this:

Create an organization on Sourcegraph for your team
Add all members of your team to the organization
When creating the batch change, select the organization's namespace instead of your namespace. This can be done via the UI or using the -namespace flag with src batch preview/apply
The batch change will now be created under the organization's namespace
All members of the organization (your team) will have admin permissions to manage the batch change

So, by using an organization's namespace, you can create a batch change that is owned and editable by the entire team, not just yourself.

Running Batch Change Server Side

Can large batch changes execution be distributed on multiple executors?

They can! Each changeset that is computed can be assigned to a separate executor, provided there are enough executors available.

What additional resources do I need to provision to run batch changes server-side?

See deploying executors page. You'll require little as a single compute instance and a docker registry mirror if you just want to process batch changes at a small scale; an autoscaling group of instances if you want to process large batch changes very fast.

Can someone accidentally take down the Sourcegraph instance if they run too big a batch change?

No. Executors have been designed for the Sourcegraph instance to offload resource-intensive tasks. The Sourcegraph instance itself only queues up batch changes for processing, tracks execution, then uses the resulting diffs to open and track changesets just as it would for batch changes created locally using the src-cli.

I have several machines configured as executors, and they don't have the same specs (eg. memory). Can I submit some batch changes specifically to a given machine?

No, for now all executors are equal in the eyes of Sourcegraph. We suggest using only one type of machine.

What happens if the execution of a step fails?

If the execution of a step on a given repository fails, that repository will be skipped, and execution on the other repositories will continue. Standard error and output will be available to the user for debugging purposes.

How do executors interact with code hosts? Will they clone repos directly?

Executors do not interact directly with code hosts. They behave in a way similar to src CLI today: executors interact with the Sourcegraph instance, the Sourcegraph instance interacts with the code host. In particular, executors download code from the Sourcegraph instance and executors do not need to access code hosts credentials directly.

From Campaigns to Batch Changes

We are sunsetting the name Campaigns and renaming it to Batch Changes starting from Sourcegraph version 3.26 (released 2021-03-20). The name change happened so that it is more descriptive and approachable for new users.

What action should I take?

Campaigns is called Batch Changes from Sourcegraph v3.26
We recommend migrating and upgrading to the latest Sourcegraph version to benefit from the new functionalities
There are no breaking changes in release 3.26 to 3.33, and URLs, CLI commands, and API endpoints using the previous name (campaigns) will still work. These will be removed in Sourcegraph 3.34.

What changes with the name change?

Campaigns is replaced by Batch Changes in the GUI, docs, customer and internal material
<sourcegraph-instance>/campaigns/* URLs are changed to <sourcegraph-instance>/batch-changes/*
The CLI prompt src campaigns is replaced by src batch
Campaign specs are now called batch specs

What's the deprecation plan?

From v3.26 to v3.33 (inclusive):

All <sourcegraph-instance>/campaigns/* URLs are deprecated. They will still work and will be removed in the future
The CLI prompt src campaigns and its alias src campaign are deprecated. They will still work and will be removed in the future
campaigns GraphQL API endpoints are deprecated. They are intended to work, so contact us if you are querying the GraphQL API to ensure we can support you. They will be removed in the future

From v3.34:

All <sourcegraph-instance>/campaigns/* URLs are removed
The CLI prompt src campaigns and its alias src campaign are removed
/campaigns GraphQL API endpoints are removed