Azure Pipelines for Rust

Getting Azure Pipelines and its connection to GitHub set up correctly is not entirely straightforward. This document takes you through exactly the steps you need to do. Stray from these at your own risk.

Setting up Azure DevOps

Azure loves to try to get you to sign in to GitHub using OAuth, thereby giving them access to all your public and private repos. This makes us sad. Here’s how you do it “the new way” instead.

First, make sure you have the Azure Pipelines GitHub Application installed:

Then, make sure you have an Azure Project for your GitHub organization:

Note that Azure associates only one of your projects with a given organization’s GitHub Apps install, so you cannot have multiple Azure Projects that are linked to different GitHub projects under the same GitHub user/organization. This is stupid, but such is life.

This template uses Build stages, which is a preview feature of Azure Pipelines. You therefore need to enable support for it. To do so, click your profile icon in the top-right corner and click “Preview features”. In the drop-down at the top in the panel that appears, choose “for this organization”, then enable “Multi-stage pipelines”.

Adding CI for a GitHub repository

At this point I’ll assume you have an Azure Project correctly set up for your GitHub user or organization (as described above).

Before we continue, there’s a fun little step you have to do first. Go to “Project settings” (bottom left), the “Service connections” (under “Pipelines”). There should be one thing listed there, and it’s your authenticated connection to GitHub. Note down its name.

Now, create a file azure-pipelines.yml in the root of the repository you want CI for. If you want all the bells and whistles, write:

stages:
 - template: azure/stages.yml@templates

resources:
  repositories:
    - repository: templates
      type: github
      name: crate-ci/azure-pipelines
      endpoint: PLACEHOLDER

Where PLACEHOLDER is the service connection name we found above. The template also has a number of configuration options with opinionated defaults. If you have a particularly “weird” project, you can also mix-and-match individual CI components.

Once that’s all committed and pushed, it’s time to set up the Pipeline in Azure:

Hopefully Azure was now happy with your efforts. If it is, you’ll be taken to your new shiny “Pipeline summary” page, and it will show you your build and tests progress! Congrats, you now have Azure Pipelines CI! If you instead get a big red box at the top of the “Run pipeline” box with an error, try to see if you can figure out which part of the magic incantation you missed. If it all looks right to you, file an issue!

Code coverage

This pipeline is also set up to use tarpaulin and codecov.io for test coverage reporting. To enable this, here’s what you have to do:

Note that this gives access to your Codecov API key to anyone with push access to the repository! Use it wisely. Forks of your repository do not have access to secrets by default.

Now just add this to your entries in azure-pipelines.yml that use the templates azure/stages.yml or azure/coverage.yml:

parameters:
 codecov_token: $(CODECOV_TOKEN_SECRET)

You may also want to give yourself a nice badge! Just go to the Settings page on codecov.io again and click “Badge” on the left. To add it your crates.io page, add this to Cargo.toml:

codecov = { repository = "GH_USER/GH_PROJECT", branch = "master", service = "github" }

Code coverage for PRs

If you are really sure you want to allow coverage to run for the arbitrary code people may submit in PRs to see your secrets, here’s what you do:

If you instead want to simply skip coverage on pull requests, do not check the box next to “Make secrets available to builds of forks”. You should not need to change anything else.