Deployment with GitHub Releases

Let's start by defining the build job in our new workflow file, which is substantively the same as our previous job.

In real projects, these jobs tend to deviate slightly, as a release builds usually have different requirements from a CI build whose only purpose is to determine if a PR is safe to merge.

But, in our simple project, our release build can be exactly the same as our CI build:

1name: Release
2
3on:
4  push:
5    tags:
6      - "v*"
7
8permissions:
9  contents: write
10
11jobs:
12  # This is identical to the job in ci.yml
13  build:
14    strategy:
15      matrix:
16        os: [ubuntu-latest, windows-latest, macos-latest]
17    runs-on: ${{ matrix.os }}
18
19    steps:
20      - name: Check out code
21        uses: actions/checkout@v4
22      - name: Set up vcpkg
23        uses: lukka/run-vcpkg@v11
24      - name: Configure CMake
25        run: cmake --preset release
26      - name: Build project
27        run: cmake --build --preset release
28      - name: Run tests
29        run: ctest --preset release
30
31      - name: Package Libraries
32        run: cpack --preset dev-zip
33      - name: Upload Libraries
34        uses: actions/upload-artifact@v4
35        with:
36          name: Greeter-Development-${{ matrix.os }}
37          path: build/Greeter-*-Development.zip
38
39      - name: Package Application
40        if: matrix.os == 'windows-latest'
41        run: cpack --preset windows-release-installer
42      - name: Upload Application
43        if: matrix.os == 'windows-latest'
44        uses: actions/upload-artifact@v4
45        with:
46          name: Greeter-Installer-${{ matrix.os }}
47          path: build/Greeter-*.msi

Once our build jobs are complete across all 3 platforms (matrix.os), we need one more job to actually create the release. It gathers the artifacts generated from the previous jbos, and performs the public-facing actions of creating the release and uploading those assets.

The complete job is below, and we'll walk through its two steps in the next sections:

1name: Release
2
3on:
4  push:
5    tags:
6      - "v*"
7
8permissions:
9  contents: write
10
11jobs:
12  build:
13    # ... (unchanged from above)
14
15  release:
16    needs: build
17    runs-on: ubuntu-latest
18
19    steps:
20      - name: Download all build artifacts
21        uses: actions/download-artifact@v4
22        with:
23          path: artifacts
24      - name: Create GitHub Release
25        uses: softprops/action-gh-release@v2
26        with:
27          name: Release ${{ github.ref_name }}
28          body: |
29            Automated release of ${{ github.ref_name }}.
30            Add a description to this draft
31          files: |
32            artifacts/**/*.zip
33            artifacts/**/*.msi
34          generate_release_notes: true
35          append_body: true
36          draft: true
37          prerelease: false

The needs: build key establishes a dependency, guaranteeing that the release job will not start until all jobs in the build matrix have finished successfully.

We don't need a strategy matrix here, as we only want to create a single release for each run of this workflow. We could use any runner that has the tools we need. A Linux runner like ubuntu-latest tends to be the default choice for platform-agnostic tasks like this, as they're cheaper than Windows/macOS runners.

Step 1: Download All Artifacts

The first step in our release job is to collect all the packages that the build jobs created. The actions/download-artifact action does this for us. With the default settings, it downloads all artifacts from the current workflow run:

1# In jobs: -> release: -> steps:
2- name: Download all build artifacts
3  uses: actions/download-artifact@v4
4  with:
5    path: artifacts

The path: artifacts input tells the action to place all downloaded artifacts into a single parent directory named artifacts. Inside, it will create subdirectories for each artifact, matching the names we gave them in the upload step. Our file system on the runner will look something like this:

1artifacts/
2├─ package-windows-latest/
3│  ├─ Greeter-1.0.0-win64.zip
4│  └─ Greeter-1.0.0.msi
5├─ package-ubuntu-latest/
6│  └─ Greeter-1.0.0-Linux.zip
7└─ package-macos-latest/
8   └─ Greeter-1.0.0-Darwin.zip

The official documentation for actions/download-artifact is available here.

If we want to understand what's going on in our runner, we can add additional steps purely to provide status updates in our workflow log. This can be particularly helpful when we need to debug things.

For example, after our actions/download-artifact step, we could list the contents of our artifacts/ directory using a simple step that runs the find command:

1- name: Display artifact structure
2  run: find artifacts

Step 2: Create the GitHub Release

With our artifacts downloaded and in our runner's /artifacts directory, we can create the actual release on GitHub. We'll use the softprops/action-gh-release action for this:

1# In jobs: -> release: -> steps:
2- name: Create GitHub Release
3  uses: softprops/action-gh-release@v2
4  with:
5    draft: true
6    name: Release ${{ github.ref_name }}
7    body: |
8      Automated release of ${{ github.ref_name }}.
9      Add a description to this draft
10    append_body: true
11    files: |
12      artifacts/**/*.zip
13      artifacts/**/*.msi
14    generate_release_notes: true
15    prerelease: false

The full documentation for softprops/action-gh-release is available here. In our example, we used the following options:

• draft: Creating a draft release means our workflow won't immediately make our release public. It gives us the opportunity to review and edit its output before we publish it for everyone to see.
• name: The title for our release. The github.ref_name context variable contains just the tag name itself (e.g., v1.0.0), which we use to create a friendly title like "Release v1.0.0".
• body: This is where we would describe our release. What new features did we add? What bugs did we fix? In this case, we've just added some placeholder content, which we can replace using the GitHub UI whilst our release is still in draft. We discuss ways to automate this later.
• append_body: This setting is relevant if we push the same tag multiple times, meaning this workflow would be updating a release that already exists. Using append_body means the body of the updated release (the placeholder content in this workflow) won't overwrite the release notes we might have added added to the existing release.
• files: The list of files we want included in the release. We can specify exact file names or, in this case, globbing patterns to select files that match a pattern. The artifacts/ subdirectory we're using here corresponds to the path we set in the previous step.
• generate_release_notes: GitHub includes the ability to automatically generate release notes, based on the PRs that have been merged to this branch since the previous release. Documentation on how this works, and how we can configure it, is available here.
• prerelease: GitHub includes the ability to flag releases as "prereleases". This indicates to users that the release is not production ready, but provided if they want to test or experiment with upcoming features. We're setting this to false here, but we can edit it through the GitHub UI once our draft release is created.

Once we've committed and pushed our release.yml worfklow to our remote repository, drafting a new release is extremely quick.

When a version is deemed ready for release, we simply create and push a version tag:

1git tag v1.1.0

1git push origin v1.1.0

GitHub Actions detects the new tag and triggers the Release workflow. We can see this from the "Actions" tab of our repository:

When it completes, a new, fully-populated draft release appears on the repository's "Releases" page, ready for us to review, edit and publish:

Congratulations! You have reached the end of this course.

We began in Chapters 1 and 2 by dissecting the fundamental C++ build process. We moved from raw compiler and linker commands to understanding the need for project organization and a build system.

In Chapters 3 through 5, we were introduced to CMake. We learned its core language - variables, lists, and control flow - and, most importantly, the modern, target-centric philosophy. We learned to think of our projects not as a list of files, but as a dependency graph of targets with properties.

Chapters 6 through 9 taught us how to manage the complexities of real-world development. We handled different platforms, architectures, and build configurations. We learned how to integrate external dependencies using find_package() and FetchContent, and then introduced package managers like vcpkg and Conan. We also introduced CMake Presets as the primary way we issue commands, streamlining our workflow.

In Chapters 10 through 13, we moved beyond compilation to cover common production requirements. We integrated code generators with custom commands, created developer utilities with custom targets, and built a quality assurance pipeline with automated testing, memory sanitization, performance benchmarking, and static analysis.

Finally, in this chapter, we placed our code under version control with Git and built a complete Continuous Integration and Continuous Delivery (CI/CD) pipeline. We automated our builds, tests, packaging, and, in this final lesson, our releases.

A solid build system is the bedrock of any successful software project, and you are now equipped with the knowledge to build that foundation. Thank you for taking this course!