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:
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.
You can create or update a campaign from a campaign spec, which is a YAML file that defines a campaign. You then use the Sourcegraph CLI (src
) to apply the campaign spec.
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
Get started by running the following Sourcegraph CLI (src
) command:
src campaign preview -f YOUR_CAMPAIGN_SPEC.campaign.yaml -namespace USERNAME_OR_ORG
Don'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 proceeding.
The namespace
can be your Sourcegraph username or the name of a Sourcegraph organisation under which you want to create the camapign.
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.
After you've applied a campaign spec, 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:
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 by changing the published: false
in your campaign spec to true
:
name: hello-world # ... changesetTemplate: # ... published: false
Then run the src campaign preview
command again, or src campaign apply
to immediately publish the changesets.
In the Sourcegraph web UI you'll see a progress indicator for the changesets that are being published. Any errors will be shown, and you can retry publishing after you've resolved the problem by running src campaign apply
again. 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.
In the list of changesets, you can see the detailed status for each changeset.
If you lack read access to a repository, you can only see limited information about the changes to that repository.
Campaigns are identified by their name. It must be unique within a single namespace (your user account on Sourcegraph, or an organization you are a member of). Updating a campaign works by targetting an existing campaign in the namespace by specifying the name in the spec. If the name matches an existing campaign, it will update the campaign. (Otherwise, a new campaign will be created.)
You can edit a the campaign's description, and any other part of its campaign spec at any time.
To update a campaign, you need admin access to the campaign, and write access to all affected repositories with published changesets.
Update the campaign spec to include the changes you want to make to the campaign. For example, change the description
of the campaign or change the commit message in the changesetTemplate
.
In your terminal, run the Sourcegraph CLI (src
) command shown. The command will execute your campaign spec to generate changes and then upload them to the campaign for you to preview and accept.
src campaign preview -f YOUR_CAMPAIGN_SPEC.campaign.yaml -namespace USERNAME_OR_ORG
Don't worry! Before any branches or changesets are modified, you will see a preview of all changes and can confirm before proceeding.
Open the preview URL that the command printed out.
Examine the preview. Confirm that the changes are what you intended. If not, edit your campaign spec 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.
You can track existing changests by adding them to the campaign spec under the importChangesets
property.
The following example campaign spec tracks five existing changesets in different repositories on different code hosts:
name: track-important-milestone description: Track all changesets related to our important milestone importChangesets: - repo: github.com/sourcegraph/sourcegraph externalIDs: [12374, 11675] - repo: bitbucket.sgdev.org/SOUR/vegeta externalIDs: [8] - repo: gitlab.sgdev.org/sourcegraph/src-cli externalIDs: [113, 119]
Create a campaign from the campaign spec by running the following Sourcegraph CLI (src
) command:
src campaign preview -f YOUR_CAMPAIGN_SPEC.campaign.yaml -namespace USERNAME_OR_ORG
Open the preview URL that the command printed out.
Examine the preview. Confirm that the changesets are the ones you intended to track. If not, edit the campaign spec and then rerun the command above.
Click the Create campaign button.
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 decide not to proceed with making 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.
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.