In this article I\u2019m providing a crash course on what GitHub Actions are and how to use it for your C++ and Qt projects.<\/p>\n\n\n\n
Tl;DR<\/h2>\n\n\n\n
GitHub has a built-in CI\/automation system called \u201cGitHub Actions\u201d that:<\/p>\n\n\n\n
- \n
- You configure<\/a> through YAML files in
.github\/workflows<\/code><\/li>\n\n\n\n- Can run on GitHub-provided cloud runners or on-prem\n
- \n
- For MacOS, Windows and Linux<\/li>\n\n\n\n
- Can run in containers too<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Is free<\/strong> on cloud runners for public repositories (and for private you get some build minutes for free too)<\/li>\n\n\n\n
- Allows packaging common CI routines into reusable components. There\u2019s a marketplace for them: https:\/\/github.com\/marketplace?type=actions<\/a><\/li>\n<\/ul>\n\n\n\n
What are GitHub Actions?<\/h2>\n\n\n\n
GitHub Actions (GHActions from now on) is a continuous integration system available on GitHub.<\/p>\n\n\n\n
It\u2019s configured in the repository\u2019s
.github\/workflows<\/code> folder. The system is very flexible and configurable. See https:\/\/docs.github.com\/en\/actions<\/a><\/p>\n\n\n\nEach file there is a workflow<\/strong>. Workflows can have multiple jobs<\/strong> that can run in parallel or in a sequence. Each job has steps<\/strong>, i.e. actual commands that run for this job.<\/p>\n\n\n\n
Workflows can be triggered by events<\/strong> happening in the repository. Events don\u2019t necessarily have to do anything with code, there\u2019s tons of them.<\/p>\n\n\n
\n![\"Conceptual](\"https:\/\/www.kdab.com\/wp-content\/uploads\/stories\/image2023-6-2_9-26-37.png\")
<\/figure><\/div>\n\n\nFor example, creating a new issue in your repository is an event. You can then have an action that will look into the created issue and e.g. welcome the first-time contributor or check if the issue description contains appropriate information. You can also trigger the workflow through API from outside, manually, or make it run on a cron schedule: https:\/\/docs.github.com\/en\/actions\/using-workflows\/events-that-trigger-workflows<\/a><\/p>\n\n\n\n
That\u2019s an important thing to take away: GitHub Actions is for much more than code, you can automate things around all aspects of your repo.<\/em><\/p>\n\n\n\n
Where are actions executed?<\/h2>\n\n\n\n
Github actions can be executed on two targets:<\/p>\n\n\n\n
- \n
- On GitHub-provided cloud runners (like in the example below) running on Azure.<\/li>\n\n\n\n
- On self-hosted runners<\/strong> that you provide yourself and hook up to your GitHub account (see self-hosted runners documentation<\/a>)<\/li>\n<\/ul>\n\n\n\n
To learn more about specs and what software is available on GitHub runners, consult this documentation page: https:\/\/docs.github.com\/en\/actions\/using-github-hosted-runners\/about-github-hosted-runners<\/a><\/p>\n\n\n\n
With both of these options, you can run your workflow directly on the operating system of the runner, or you can run your workflow in a Docker container:\u00a0https:\/\/docs.github.com\/en\/actions\/using-jobs\/running-jobs-in-a-container<\/a><\/p>\n\n\n\n
Matrices<\/h2>\n\n\n\n
One interesting feature similar to other CI systems is a\u00a0
matrix<\/code>. You can define axes of some values and have GHActions generate jobs automatically based on the combination of the values from the axes:<\/p>\n\n\n\njobs:\r\n example_matrix:\r\n strategy:\r\n matrix:\r\n version: [10, 12, 14]\r\n os: [ubuntu-latest, windows-latest]<\/code><\/pre>\n\n\n\nExtensibility<\/h2>\n\n\n\n
Steps in jobs can be packaged to reusable components called (ekhm) actions<\/strong>. Action can have inputs and outputs. Custom actions can be written in JavaScript<\/a><\/p>\n\n\n\n
You use actions created by you or other people by adding the
uses:<\/code> clause in your step:<\/p>\n\n\n\n- name: Setup VS\r\n uses: ilammy\/msvc-dev-cmd@v1 # action from some kind person on GitHub\r\n- uses: .\/.github\/actions\/setup-rust # action from your own repository<\/code><\/pre>\n\n\n\nThere\u2019s also a way to call workflows from other workflows: https:\/\/docs.github.com\/en\/actions\/using-workflows\/reusing-workflows<\/a>.<\/p>\n\n\n\n
GitHub itself provides tons of such actions as separate small repos: https:\/\/github.com\/actions\/<\/a><\/p>\n\n\n\n
Example<\/h2>\n\n\n\n
I created a tiny QML application (basically the template from Qt Creator) and set up GHActions for it. You can see the repository at https:\/\/github.com\/MiKom\/QtQuickApp<\/a>.<\/p>\n\n\n\n
It\u2019s driven by a workflow file located at\u00a0
.github\/workflows\/build.yaml<\/code>. Replicated here:<\/p>\n\n\n\nname: CI\r\n \r\non: push # when to trigger this. Here, on every push\r\njobs:\r\n build_and_test:\r\n name: \"Build and test\"\r\n strategy:\r\n matrix:\r\n os: [ubuntu-latest, windows-latest] # we build on GitHub-provided Windows and Linux images\r\n runs-on: ${{ matrix.os }} # use value from the matrix\r\n steps:\r\n - name: Install dependencies (linux)\r\n run: sudo apt install ninja-build\r\n if: matrix.os == 'ubuntu-latest' # conditional, runs this step only on the Ubuntu runner\r\n - name: Install Ninja (windows) # Ninja is not available in GitHub-provided images,\r\n # see https:\/\/github.com\/actions\/runner-images\/issues\/514\r\n run: choco install ninja # So let's install it through Chocolatey\r\n if: matrix.os == 'windows-latest'\r\n - name: Install Qt\r\n uses: jurplel\/install-qt-action@v3\r\n with:\r\n version: '6.5.2'\r\n - uses: ilammy\/msvc-dev-cmd@v1 # This action essentially calls vcvarsall.bat for the latest VS in the runner for x64\r\n - uses: actions\/checkout@v3 # Actually check out the sources. GH Actions can run for events that may not require\r\n # sources (e.g. when someone comments on an issue)\r\n \r\n # Here we call CMake manually, there are solutions for that in the Marketplace: https:\/\/github.com\/marketplace\/actions\/run-cmake\r\n - name: Build\r\n # We don't need to set up the environment variable for CMake to see Qt because the install-qt-action\r\n # sets up the necessary variables automatically\r\n run: cmake -S . -B build -G \"Ninja Multi-Config\" && cmake --build build --config Debug<\/code><\/pre>\n\n\n\nNotice how I used the community-provided action for installing Qt. For more information, see https:\/\/github.com\/marketplace\/actions\/install-qt<\/a>. To generate the configuration for your Qt needs for this action see https:\/\/ddalcino.github.io\/aqt-list-server\/<\/a><\/p>\n\n\n\n
You can view the results of running this workflow in the \u201cActions\u201d tab of your repository:<\/p>\n\n\n
\n![\"\"](\"https:\/\/www.kdab.com\/wp-content\/uploads\/stories\/github_action_run-1024x713.png\")
<\/a><\/figure><\/div>\n\n\nBut GitHub is cloud\/proprietary\/closed source!<\/h2>\n\n\n\n
It\u2019s understandable to be reluctant to lock-in to a service provided by an SaaS company. Thankfully, there\u2019s an open-source re-implementation of GitHub Actions called Act<\/a>. It was designed to let you run your workflows locally.<\/p>\n\n\n\n
Gitea<\/a>, an open-source git hosting solution is now integrating a fork of Act. The feature is described in Gitea\u2019s documentation: https:\/\/docs.gitea.com\/usage\/actions\/overview<\/a>.<\/p>\n\n\n\n
It\u2019s source-compatible with GitHub actions so if your workflows are using the subset of features supported by Gitea, the migration should be rather painless.<\/p>\n\n\n\n
Further reading<\/h2>\n\n\n\n
There\u2019s a lot more to GHActions than is described here. Deployments, secrets management, environments, cacheing, artifacts storage and sharing, you name it. Learn more at https:\/\/docs.github.com\/en\/actions<\/a><\/p>\n\n\n\n
A good way to learn is also to look at repositories that already do stuff through GHActions, like Slint: https:\/\/github.com\/slint-ui\/slint\/blob\/master\/.github\/workflows\/ci.yaml<\/a><\/p>\n\n\n\n
Also, when you try to add an action, you can choose from many templates as a starting point:<\/p>\n\n\n
\n![\"\"](\"https:\/\/www.kdab.com\/wp-content\/uploads\/stories\/github_actions_templates-1024x917.png\")
<\/figure><\/div>\n\n\nConclusion<\/h2>\n\n\n\n
GitHub Actions is a very flexible system that you may use if you host your stuff on GitHub. It seems to implement everything you\u2019d expect from a modern CI system and more.<\/p>\n\n\n\n
- Allows packaging common CI routines into reusable components. There\u2019s a marketplace for them: https:\/\/github.com\/marketplace?type=actions<\/a><\/li>\n<\/ul>\n\n\n\n
- Can run on GitHub-provided cloud runners or on-prem\n