Build Servers and Continuous Integration

The ubuntu-latest runner that GitHub Actions provides is a convenient starting point. Common tools that most C++ projects need are preinstalled, such as a compiler, Git, and CMake.

However, almost all projects need some additional tools, too. For example, our project depends on vcpkg to manage its libraries, and the default runner doesn't have that.

The base environment is just a starting point; it's our job to add a few steps to the workflow to install any additional tools or dependencies our build requires.

Let's look at the two most common ways to install a tool like vcpkg in our workflow.

Approach 1: Manual Installation

This approach involves running the exact same commands in your workflow's run step that you would run on your own local Linux machine to install the tool. This gives you complete control but can be more verbose.

For vcpkg, this means cloning the repository and running its bootstrap script, just like we did on our own machine earlier.

In this example, we're downloading vcpkg to the ~/vcpkg directory of our Ubuntu host, and then running the bootstrap script that we just downloaded::

1name: C++ CI
2
3on:
4  pull_request:
5    branches: [ "main" ]
6
7jobs:
8  build-and-test:
9    runs-on: ubuntu-latest
10    - name: Check out code
11      uses: actions/checkout@v4
12
13    - name: Install vcpkg
14      run: |
15        git clone https://github.com/microsoft/vcpkg.git ~/vcpkg
16        ~/vcpkg/bootstrap-vcpkg.sh
17      shell: bash # Explicitly use bash for the script

Approach 2: Using a GitHub Action

The manual approach works, but it has downsides. You have to write and maintain the installation script yourself. A better way is often to use a pre-made action from the GitHub Marketplace.

For pretty much any common requirement, such as installing vcpkg, someone has already made and shared a free script that will do the work for us.

For vcpkg, the lukka/run-vcpkg action (documented here) is commonly used. It handles all the details of installing vcpkg and its dependencies for you.

Note that this action requires we provide a baseline for vcpkg. This is a good practice anyway, so let's ensure our vcpkg.json includes one:

1{
2  "name": "greeter",
3  "dependencies": [
4    "gtest",
5    "spdlog",
6    "benchmark"
7  ],
8  "builtin-baseline":
9    "44a1e4eca5211434b5fefcc25a69bba246c3f861"
10}

We covered vcpkg baselines and how to set them up earlier in the course .

With our baseline set, we can now add the action to our workflow:

1name: C++ CI
2
3on:
4  pull_request:
5    branches: [ "main" ]
6
7jobs:
8  build-and-test:
9    runs-on: ubuntu-latest
10    - name: Check out code
11      uses: actions/checkout@v4
12
13    - name: Set up vcpkg
14      uses: lukka/run-vcpkg@v11

Where an established, prebuilt action is available, using it is generally recommended over the manual approach. The action's author maintains the script, ensuring it works correctly.

These scripts often also include options we can change and features we can enable or disable. The options for lukka/run-vcpkg are listed on its GitHub page.

In our previous chapters, we made our CMakePresets.json portable by reading the path to vcpkg from an environment variable: $env{VCPKG_ROOT}.

This makes things a lot easier - we now just need to define this variable as part of our workflow so that when CMake runs and processes our preset, it can find the toolchain file.

Setting environment variables is a pretty fundamental requirement supported by every CI provider. In GitHub Actions, we do this via the env key.

This can be set for the entire job, or just for an individual step:

1jobs:
2  some-job:
3    runs-on: ubuntu-latest
4
5    # Set an env variable for all steps in this job
6    env: 
7      SOME_VARIABLE: Some value 
8
9    steps:
10    - name: Some Step
11      run: some-command
12      # Set an env variable for just this step
13      env: 
14        ANOTHER_VARIABLE: Another value

For the VCPKG_ROOT variable, this will need to be set at the job level, as it will be required by multiple steps.

• The "Install vcpkg" step will read it to ensure it installs vcpkg at the location we requested.
• The "configure CMake" step (which we'll add later) will read to to understand where vcpkg's toolchain file is.

Setting VCPKG_ROOT in the Workflow

The lukka/run-vcpkg action sets the VCPKG_ROOT environment variable automatically, which is another reason why using dedicated actions is often the preferred approach.

However, let's assume we we needed to install vcpkg manually, so we can walk through a generic process that works for any task.

We'll set our VCPKG_ROOT path to be relative to the workspace directory. GitHub provides a variable for this in the form of github.workspace:

1jobs:
2  build-and-test:
3    runs-on: ubuntu-latest
4
5    # Set environment variables for all steps in this job
6    env: 
7      VCPKG_ROOT: ${{ github.workspace }}/vcpkg 
8
9    steps:
10    - name: Check out code
11      uses: actions/checkout@v4
12
13    - name: Install vcpkg
14      run: |
15        git clone https://github.com/microsoft/vcpkg.git ${{ env.VCPKG_ROOT }} 
16        ${{ env.VCPKG_ROOT }}/bootstrap-vcpkg.sh 
17      shell: bash

Let's break down the new additions:

• env:: We set this environment variable at the job level,
• VCPKG_ROOT: ${{ github.workspace }}/vcpkg: We define the VCPKG_ROOT variable. The value ${{ github.workspace }} is a GitHub Actions context variable that points to the root of our checked-out repository on the runner. We're telling the workflow that vcpkg will live in a vcpkg subdirectory within our workspace.
• ${{ env.VCPKG_ROOT }}: Inside the run step, we can now use this syntax to access the environment variable we just defined. This ensures our git clone and bootstrap commands use the exact same path, setting up vcpkg at the location we specified in our variable.

With this env block in place, any subsequent step in this will run in an environment where VCPKG_ROOT is correctly set. This also means our CMake preset will have access to it, and construct the correct path to the toolchain file.

1{
2  "version": 3,
3  "configurePresets": [
4    {
5      "name": "default",
6      "binaryDir": "${sourceDir}/build",
7      "toolchainFile":
8        "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
9     },
10     // ...
11  ],
12  // ...
13}

Now that we have our build environment set up, we're ready to add the steps that build and test our code.

Now let's add the steps to actually build our project. The ubuntu-latest runner comes with a C++ compiler and CMake pre-installed, so we don't need to worry about setting those up.

We will add two new steps to our job. These steps will use the run key to execute shell commands, just as if we were typing them into a terminal. And thanks to the CMakePresets.json file we created in the previous chapters, the commands are simple and clean.

In some situations, we may want to add presets that are specifically dedicated to our CI requirements. We'd add those to CMakePresets.json just like any other preset.

In our case, the default presets work fine:

1name: C++ CI
2
3on:
4  pull_request:
5    branches: [ "main" ]
6
7jobs:
8  build-and-test:
9    runs-on: ubuntu-latest
10    steps:
11    - name: Check out code
12      uses: actions/checkout@v4
13      
14    - name: Set up vcpkg
15      uses: lukka/run-vcpkg@v11
16
17    - name: Configure CMake
18      run: cmake --preset default
19
20    - name: Build project
21      run: cmake --build --preset default

When this workflow runs, it will first check out the code, then install vcpkg, run the standard CMake configure step, and finally run the build step.

If any of these commands fails (i.e., returns a non-zero exit code), the step will fail, and the entire job will stop and be marked as a failure.

Let's create such a failure so we can confirm everything is working. In greeter/src/Greeter.cpp, we no longer want to ignore Bob, so lets clumsily try to remove this feature, leaving a compilation error:

1#include <greeter/Greeter.h>
2
3Greeter::Greeter(std::string name)
4  : name_(std::move(name)) {}
5
6namespace {
7bool should_ignore(const std::string& Name) {
8  return Name == "Bob";
9}
10}
11
12std::string Greeter::greet() const {
13  // This will now be a compilation error
14  if (should_ignore(name_)) return "";
15  return "Hello, " + name_ + "!";
16}

Let's commit and push our changes to the ci.yml and Greeter.cpp files:

1git add .

1git commit -m "Stop ignoring Bob"

1git push

Once our changes are pushed, GitHub should notice a PR targeting the main branch has been updated, and that matches the condition in one of our workflows:

1# ...
2
3on:
4  pull_request:
5    branches: [ "main" ]
6    
7# ...

Therefore, it should jump into action and run our workflow again:

When our build server attempts to compile our project, our workflow will fail and the error will be reported, so we know our branch is not safe to merge in its current state:

With the default GitHub settings, we can still merge a PR even with failing checks, but we can configure that from our repository settings if we wish. We configure it by updating the rules for our main branch under Rules > Rulesets > Require status checks to pass.

Fixing CI Errors

To understand why an action failed, we can retrieve the logs by clicking the "..." button next to failure on the PR, or from the "Actions" tab at on the top menu. Ideally, our workflow will have failed for exactly the reason we expect - the compiler error we introduced:

If we fix our error, create a new commit on our branch, and then push our changes, the job should rerun and report the success:

1#include <greeter/Greeter.h>
2
3Greeter::Greeter(std::string name)
4  : name_(std::move(name)) {}
5
6std::string Greeter::greet() const {
7  if (should_ignore(name_)) return "";
8  return "Hello, " + name_ + "!";
9}

1git add .

1git commit -m "Fix compilation error"

1git push

Ensuring our code compiles is a good first step for our CI process, but we usually want to perform other checks too. Most notably, we typically want to ensure our tests pass.

We can add this step in the way you might expect, extending our job with an additional step that invokes ctest:

1name: C++ CI
2
3on:
4  pull_request:
5    branches: [ "main" ]
6
7jobs:
8  build-and-test:
9    runs-on: ubuntu-latest
10    steps:
11    - name: Check out code
12      uses: actions/checkout@v4
13
14    - name: Configure CMake
15      run: cmake --preset default
16
17    - name: Build project
18      run: cmake --build --preset default
19
20    - name: Run tests
21      run: ctest --preset default

Now, when we commit and push this change to our workflow, we should see our CI server running our unit tests, and failing as the test suite doesn't pass:

1git add .

1git commit -m "Run test suite on CI"

1git push

Let's fix our tests, and then commit and push one last time to see our full CI pipeline validating our PR as being complete and good to merge:

1#include <gtest/gtest.h>
2#include <greeter/Greeter.h>
3#include <tuple>
4
5class GreeterNameTest :
6  public testing::TestWithParam<
7    std::tuple<std::string, std::string>
8  > {};
9
10TEST_P(GreeterNameTest, GreetsCorrectlyForName) {
11  auto [name, expected_greeting] = GetParam();
12  Greeter greeter = name.empty() ? Greeter() : Greeter(name);
13  EXPECT_EQ(greeter.greet(), expected_greeting);
14}
15
16INSTANTIATE_TEST_SUITE_P(
17  NamedGreetings,
18  GreeterNameTest,
19  testing::Values(
20    std::make_tuple("", "Hello, User!"),
21    std::make_tuple("John", "Hello, John!"),
22    std::make_tuple("Jane", "Hello, Jane!")
23    std::make_tuple("Bob", "")
24  )
25);

1git add .

1git commit -m "Fix broken test"

1git push

In this lesson, we've set up a complete Continuous Integration pipeline, elevating our project from a local build to a fully automated workflow.

• Continuous Integration (CI): This practice of automatically building and testing every change provides a quality gate, ensuring the stability of your main branch.
• Build Servers: A build server (like a GitHub Actions runner) provides a clean, reproducible environment.
• GitHub Actions: We learned to create a workflow in a YAML file that is triggered by pull requests.
• The CI Workflow: Our workflow now automatically performs the key steps to ensure our PR meets the quality bar: it checks out the code, configures it with CMake, builds it, and runs the test suite with CTest.