Packaging with GitHub Actions

Any files created on a CI runner are temporary. Once the job finishes, the virtual machine is destroyed, and all its files are lost. To preserve the output of a job, we need to use workflow artifacts.

An artifact is a file or a collection of files that are saved from a workflow run. Once a job is complete, you can view and download its artifacts from the workflow's summary page on GitHub.

Using the upload-artifact Action

The standard way to create an artifact is with the official actions/upload-artifact action. Let's add this as the final step in our job.

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 release
19
20      - name: Build project
21        run: cmake --build --preset release
22
23      - name: Run tests
24        run: ctest --preset release
25
26      - name: Package
27        run: cpack --preset dev-zip
28
29      - name: Upload Package Artifact
30        uses: actions/upload-artifact@v4
31        with:
32          name: Greeter-Package-Linux
33          path: build/Greeter-*-Development.zip

Let's break down the with block, which contains the inputs for this action:

• name: This is the name the artifact will have on the GitHub UI. It's a good idea to make this descriptive, including the platform.
• path: This tells the action which file(s) to upload. CPack generates filenames that include the version and architecture (e.g., Greeter-1.0.0-Linux.zip). Since this can change, we use a glob pattern (*) to match any file that starts with Greeter- and ends with -Development.zip in the build/ directory.

Now, the actions/upload-artifact will provide a link to download our package within its log output. Also, after our workflow completes, if we go to the "Summary" page for the run, we'll see a new "Artifacts" section with our package, ready to be downloaded:

GitHub Actions has a useful feature called a strategy: matrix. It allows us to define a set of configurations, and GitHub will automatically create a separate job for each combination. As an example, let's use this to create builds and packages for three platforms - Linux, Windows, and macOS.

Let's refactor our ci.yml to use a matrix. We'll define a list of operating systems and let GitHub Actions run our build-and-test job in parallel on each one:

1name: C++ CI
2
3on:
4  pull_request:
5    branches: ["main"]
6
7jobs:
8  build-and-test:
9    strategy:
10      matrix:
11        os: [ubuntu-latest, windows-latest, macos-latest]
12        
13    runs-on: ${{ matrix.os }}
14    
15    steps:
16      - name: Check out code
17        uses: actions/checkout@v4
18
19      - name: Set up vcpkg
20        uses: lukka/run-vcpkg@v11
21
22      - name: Configure CMake
23        run: cmake --preset release
24
25      - name: Build project
26        run: cmake --build --preset release
27
28      - name: Run tests
29        run: ctest --preset release
30
31      - name: Package
32        run: cpack --preset dev-zip
33
34      - name: Upload Package Artifact
35        uses: actions/upload-artifact@v4
36        with:
37          name: Greeter-Package-${{ matrix.os }}
38          path: build/Greeter-*-Development.zip

Let's examine the changes:

The strategy: matrix: os: [...] setting define a matrix with a single variable, os, with three values representing the list of runner images we want to use.

Then, instead of hardcoding a runner for the runs-on option, we use the special context syntax ${{ ... }} to access the os variable from the matrix.

We also use this variable in the name we pass to upload-artifact. This ensures each of our packages have a unique name, which will help us distinguish between them.

Now, when this workflow runs, GitHub will create three parallel jobs. The first job will run with matrix.os set to ubuntu-latest, the second with windows-latest, and the third with macos-latest.

The result is a parallel, multi-platform build from a single job definition:

This is why keeping our build scripts portable is important. If they're portable, everything will just work.

Once all of our builds are complete, our workflow summary page will show three downloadable packages - one from each of our parallel jobs:

More Examples

This example use of a matrix created an os variable, but we can use this technique to solve a wide range of problems. For example, we could create a matrix strategy to handle different build configurations, implemented by controlling which presets are used:

1name: C++ CI
2
3on:
4  pull_request:
5    branches: ["main"]
6
7jobs:
8  build-and-test:
9    strategy:
10      matrix:
11        config: [debug, release]
12    runs-on: ubuntu-latest
13    steps:
14      - name: Check out code
15        uses: actions/checkout@v4
16
17      - name: Set up vcpkg
18        uses: lukka/run-vcpkg@v11
19
20      - name: Configure CMake
21        run: cmake --preset ${{ matrix.config }}
22
23      - name: Build project
24        run: cmake --build --preset ${{ matrix.config }}
25
26      - name: Run tests
27        run: ctest --preset ${{ matrix.config }}
28
29      - name: Package
30        run: cpack --preset ${{ matrix.config }}-dev-zip
31
32      - name: Upload Package Artifact
33        uses: actions/upload-artifact@v4
34        with:
35          name: Greeter-Package-ubuntu-latest
36          path: build/Greeter-*-Development.zip

Our matrix strategy can also have multiple dimensions. This 3x2 matrix would spawn six jobs - one for every combination of os and config:

1name: C++ CI
2
3on:
4  pull_request:
5    branches: ["main"]
6
7jobs:
8  build-and-test:
9    strategy:
10      matrix: 
11        os: [ubuntu-latest, windows-latest, macos-latest]
12        config: [debug, release]
13    runs-on: ${{ matrix.os }}
14    steps:
15      - name: Check out code
16        uses: actions/checkout@v4
17
18      - name: Set up vcpkg
19        uses: lukka/run-vcpkg@v11
20
21      - name: Configure CMake
22        run: cmake --preset ${{ matrix.config }}
23
24      - name: Build project
25        run: cmake --build --preset ${{ matrix.config }}
26
27      - name: Run tests
28        run: ctest --preset ${{ matrix.config }}
29
30      - name: Package
31        run: cpack --preset ${{ matrix.config }}-dev-zip
32
33      - name: Upload Package Artifact
34        uses: actions/upload-artifact@v4
35        with:
36          name: Greeter-Package-${{ matrix.os }}-${{ matrix.config}} 
37          path: build/Greeter-*-Development.zip

In this lesson, we've integrated our CPack configuration directly into our GitHub Actions workflow, automating the packaging process.

• Automated Packaging: We added a run step to our CI workflow to execute cpack after a successful build.
• Workflow Artifacts: We used the actions/upload-artifact action to save the packages generated by CPack, making them downloadable from the workflow summary page.
• Multi-Platform Builds with Matrix: We refactored our workflow to use a strategy: matrix. This allowed us to build and package for Windows, macOS, and Linux in parallel without duplicating our workflow code.
• Using Matrix Variables: We used the ${{ matrix.os }} context variable to give each platform's artifact a unique name.