Campaigns

What are campaigns?

Campaigns are part of Sourcegraph code change management and let you make large-scale code changes across many repositories and different code hosts.

You provide the code to make the change, and campaigns provide the plumbing to turn it into a large-scale code change campaign and monitor its progress.

Are you a first time user of campaigns?

If you are a first-time user of campaigns, we recommend that you read through the following sections of the documentation:

1. Read through the How it works section below and watch the video to get an understanding of how campaigns work.
2. Go through the "Getting started" instructions to setup your Sourcegraph instance for campaigns.
3. Create your first campaign from a set of patches by reading "Creating a campaign from patches".
4. Create a manual campaign to track the progress of already-existing pull requests on your code host: "Creating a manual campaign".

At this point you're ready to explore the example campaigns and create your own action definitions and campaigns.

When should I use campaigns?

Campaigns allow you to leverage Sourcegraph's search powers and execute code and Docker containers in all the repositories yielded by a single Sourcegraph search query.

The created set of patches can then be turned into multiple changesets (a generic name for what some code hosts call pull requests and others merge requests) on different code hosts by creating a campaign.

Once the campaign is created, you can track the review state, CI status and open/closed/merged lifecycle of each changeset in the Sourcegraph UI.

You should use campaigns if you want to

• run code to make changes across a large number of repositories.
• keep track of a large number of pull requests and their status on GitHub or Bitbucket Server instances.
• execute commands to upgrade dependencies in multiple repositories.
• use Sourcegraph's search and replace matches by running code in the matched repositories.

How it works

See this video for a demonstration of lifecycle of a campaign:

1. With the src CLI the user generates a set of patches by running gofmt over every repository that has a go.mod file, leveraging Sourcegraphs search capabilities.

   This is called executing an action (an action is a series of commands and Docker containers to run in each repository) and yields set of patches, one for each repository, which you can inspect either in the CLI or in the Sourcegraph UI.

2. The patches are then used to create a draft campaign.

3. At this point, since it's a draft camapaign, no changesets (pull requests in the case of GitHub here) have been created on the code host.

4. The user then selectively creates GitHub pull requests by publishing single patches.

Requirements

• Sourcegraph instance configured for campaigns.
• src CLI: Installation and setup instructions

Limitations

Campaigns currently only support GitHub and Bitbucket Server repositories. If you're interested in using campaigns on other code hosts, let us know.