Quickstart for Campaigns
Get started and create your first Sourcegraph campaign in 10 minutes or less.
In this guide, you’ll create a Sourcegraph campaign that appends text to all
README.md files in all of your repositories.
The only requirement is a Sourcegraph instance with a some repositories in it. See the “Quickstart” guide on how to setup a Sourcegraph instance.
Configure code host connections
Campaigns need write permissions for the repositories in which you want to make changes.
Configure your code host connections to have the right permissions for campaigns:
See “Code host interactions in campaigns” for details on what the permissions are used for.
Install the Sourcegraph CLI
In order to create campaigns we need to install the Sourcegraph CLI (
Install the version of
srcthat’s compatible with your Sourcegraph instance:
curl -L https://YOUR-SOURCEGRAPH-INSTANCE/.api/src-cli/src_darwin_amd64 -o /usr/local/bin/src chmod +x /usr/local/bin/src
curl -L https://YOUR-SOURCEGRAPH-INSTANCE/.api/src-cli/src_linux_amd64 -o /usr/local/bin/src chmod +x /usr/local/bin/src
Windows: see “Sourcegraph CLI for Windows”
srcwith your Sourcegraph instance by running
src loginand following the instructions:
src login https://YOUR-SOURCEGRAPH-INSTANCE
src login reports that you’re authenticated, we’re ready for the next step.
Write a campaign spec
A campaign spec is a YAML file that defines a campaign. It specifies which changes should be made in which repositories and how those should be published on the code host.
See the “Campaign spec YAML reference” for details.
Save the following campaign spec as
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 the campaign
Let’s see the changes that will be made. Don’t worry—no commits, branches, or changesets will be published yet (the repositories on your code host will be untouched).
In your terminal, run this command:
src campaign preview -f hello-world.campaign.yaml -namespace USERNAME_OR_ORG
namespaceis either your Sourcegraph username or the name of a Sourcegraph organisation under which you want to create the campaign. If you’re not sure what to choose, use your username.
Wait for it to run and compute the changes for each repository.
When it’s done, click the displayed link to see all of the changes that will be made.
Make sure the changes look right.
If you want to modify which changes are made, edit the
hello-world.campaign.yamlfile, rerun the
src campaign previewcommand and open the newly generated preview URL.
Click the Apply spec button to create the campaign. You should see something like this:
You created your first campaign! The campaign’s changesets are still unpublished, which means they exist only on Sourcegraph and haven’t been pushed to your code host yet.
Publish the changes
So far, nothing has been created on the code hosts yet. For that to happen, we need to publish the changesets in our campaign.
Publishing causes commits, branches, and pull requests/merge requests to be created on your code host.
You probably don’t want to publish these toy “Hello World” changesets to actively developed repositories, because that might confuse people (“Why did you add this line to our READMEs?”).
On a real campaign, you would do the following:
src campaign previewcommand again and open the URL.
On the preview page you can confirm that changesets will be published when the spec is applied.
Click the Apply spec button and those changesets will be published on the code host.
You’ve created your first campaign! 🎉🎉
You can customize your campaign spec and experiment with making other types of changes.
To update your campaign, edit
hello-world.campaign.yaml and run
src campaign preview again. (As before, you’ll see a preview before any changes are applied.)
To learn what else you can do with campaigns, see “Campaigns” in Sourcegraph documentation.