Campaigns let you make large-scale code changes across many repositories.
A campaign streamlines the creation and tracking of pull requests across many repositories and code hosts. After you create a campaign, you tell it what changes to make (by providing a list of repositories and a script to run in each). The campaign lets you create pull requests on all affected repositories, and it tracks their progress until they're all merged. You can preview the changes and update them at any time.
People usually use campaigns to make the following kinds of changes:
For step-by-step instructions to create your first campaign, see Hello World Campaign in Sourcegraph Guides.
The generic term changeset is used to refer to any of the following:
A single campaign can span many repositories and many code hosts.
You can view a list of all campaigns by clicking the 
campaigns icon in the top navigation bar.
Use the filters to switch between showing all campaigns, open campaigns, or closed campaigns.
If you lack read access to a repository in a campaign, you can only see limited information about the changes to that repository (and not the repository name, file paths, or diff).
You can create or update a campaign from a campaign spec, which is a YAML file that defines a campaign.
See the "Creating a campaign" section for an example campaign spec YAML file.
For more information, see:
Creating your first campaign? See Hello World Campaign in Sourcegraph Guides for step-by-step instructions.
You can create a campaign from a campaign spec, which is a YAML file that describes your campaign.
The following example campaign spec adds "Hello World" to all README.md files:
name: hello-world description: Add Hello World to READMEs # Find all repositories that contain a README.md file. on: - repositoriesMatchingQuery: file:README.md # In each repository, run this command. Each repository's resulting diff is captured. steps: - run: echo Hello World | tee -a $(find -name README.md) container: alpine:3 # Describe the changeset (e.g., GitHub pull request) you want for each repository. changesetTemplate: title: Hello World body: My first campaign! branch: hello-world # Push the commit to this branch. commit: message: Append Hello World to all README.md files published: false
Create a campaign from the campaign spec:
src campaign apply -f YOUR_CAMPAIGN_SPEC.campaign.yaml -previewDon't worry! Before any branches are pushed or changesets (e.g., GitHub pull requests) are created, you will see a preview of all changes and can confirm each one before it's published.
Wait for it to run and compute the changes for each repository (using the repositories and commands in the campaign spec).
Open the preview URL that the command printed out.
Examine the preview. Confirm that the changes are what you intended. (If not, edit the campaign spec and then rerun the command above.)
Click the Create campaign button. TODO(sqs)
Click the campaigns icon in the top navigation bar.
In the list of campaigns, click the campaign where you'd like to apply the template.
In the campaign, click the Update template button.
In your terminal, run the command shown. The command will execute your campaign template to generate changes and then upload them to the campaign for you to preview and accept.
You need Sourcegraph CLI (
src) for this step. For reference, the command shown by the campaign is the following (withCAMPAIGN-IDfilled in):
src campaign apply -template=MY-TEMPLATE.campaign.yml -preview -campaign=CAMPAIGN-IDOpen the preview URL that the command printed out.
Examine the preview. Confirm that the changes are what you intended. (If not, edit your campaign template and then rerun the command above.)
Click the Update campaign button.
After you've applied a campaign template, you can publish 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 campaign with other people if you want their help. Any person on your Sourcegraph instance can view it in the campaigns list.
If a person viewing the campaign lacks read access to a repository in the campaign, they can only see limited information about the changes to that repository (and not the repository name, file paths, or diff).
You can update a campaign's changes at any time, even after you've published changesets. For more information, see "Updating a campaign".
The example campaigns show how to use campaigns to make useful, real-world changes:
campaigns icon in the top navigation bar.You've created a new campaign, but it's empty (it has no changesets). Next, you can:
After you've added patches, you can see a preview of the changesets (e.g., GitHub pull requests) that will be created from the patches. Publishing the changesets will, for each repository:
When you're ready, you can publish all of a campaign's changesets, or just an individual changeset.
campaigns icon in the top navigation bar.You'll see a progress indicator when changesets are being published. Any errors will be shown, and you can retry publishing after you've resolved the problem. You don't need to worry about it creating multiple branches or pull requests when you retry, because it uses the same branch name.
To publish a changeset, you need admin access to the campaign and write access to the changeset's repository (on the code host). For more information, see "Code host interactions in campaigns". Forking the repository is not yet supported.
A campaign tracks all of its changesets for updates to:
You can see the overall trend of a campaign in the burndown chart, which shows the proportion of changesets that have been merged over time since the campaign was created.
TODO(sqs) screenshot
In the list of changesets, you can see the detailed status for each changeset.
TODO(sqs) screenshot
If you lack read access to a repository, you can only see limited information about the changes to that repository (and not the repository name, file paths, or diff).
You can edit a campaign's name and description, and apply a new campaign template, at any time.
To update a campaign, you need admin access to the campaign, and write access to all affected repositories with published changesets.
campaigns icon in the top navigation bar.Changes to the campaign's name and description do not automatically propagate to all of the campaign's changesets. You need to re-apply the campaign template to propagate these changes.
Click the campaigns icon in the top navigation bar.
In the list of campaigns, click the campaign that you want to update.
In the campaign, click the *Update template button.
In your terminal, run the command shown. The command will execute your campaign template to generate changes and then upload them to the campaign for you to preview and accept.
You need Sourcegraph CLI (
src) for this step. For reference, the command shown by the campaign is the following (withCAMPAIGN-IDfilled in):
src campaign apply -template=MY-TEMPLATE.campaign.yml -preview -campaign=CAMPAIGN-IDOpen the preview URL that the command printed out.
Examine the preview. Confirm that the changes are what you intended. (If not, edit your campaign template and then rerun the command above.)
Click the Update campaign button.
All of the changesets on your code host will be updated to the desired state that was shown in the preview.
Click the campaigns icon in the top navigation bar.
To use an existing campaign: In the list of campaigns, click the campaign where you'd like to track existing changesets.
To create a new campaign: Click the ＋ New campaign button. For more information, see "Creating a new campaign".
Click the Track existing changeset button in the top right of the Changesets list.
Type in the name of the changeset's repository.
This is the repository's name on Sourcegraph. If you can visit the repository at https://sourcegraph.example.com/foo/bar, the name is foo/bar. Depending on the configuration, it may or may not begin with a hostname (such as github.com/foo/bar).
Type in the changeset number (e.g., the GitHub pull request number).
Click Add.
You'll see the existing changeset in the list. The campaign will track the changeset's status and include it in the overall campaign progress (in the same way as if it had been created by the campaign). For more information, see "Tracking campaign progress and changeset statuses".
You can close a campaign when you don't need it anymore, when all changes have been merged, or when you decided not to proceed with making all of the changes. A closed campaign still appears in the campaigns list. To completely remove it, you can delete the campaign.
Any person with admin access to the campaign can close or delete it.
campaigns icon in the top navigation bar.See "Managing access to campaigns".
All actions on the code host (such as pushing a branch or opening a changeset) are performed by your individual user account, not by a bot user. For more information, see "Code host interactions in campaigns".
Repository permissions are enforced when campaigns display information. For more information, see "Repository permissions in campaigns".
Using campaigns requires a code host connection to a supported code host (currently GitHub and Bitbucket Server).
Site admins can also:
package.json file".To learn about the internals of campaigns, see "Campaigns" in the developer documentation.