GitHub Workflows#
Purpose#
This is the primary CI interface.
Configuration#
See the .github/workflows
files.
Recommendation#
Organize the CI jobs in small reusable units such that they can be called on: push/pull, schedule, and release. This workflow design also allows to reuse the workflow defined in another project, e.g. you can use the workflows defined in this template directly.
Reusable workflows#
The main workflow logic are located in step_<Workflow>.yaml
, which contain
only the on:workflow_call
interface.
Main workflows#
The main triggering workflows are located in ci.yaml
and release.yaml
,
containing the main on:push/pull/schedule
logic, and the calls to the reusable
workflows.
Experimental jobs#
In order to properly support experimental jobs, you can use alls-green
action to get the status of the overall CI, without the failure status of the
experimental jobs.
In order to mask the overall status of the CI on the git commits, you can use
[steps.[*].continue-on-error
] as done in this template. This should not be
used outside of the main branch’s git commits.
Naming#
The name
field of the workflows, as well as the name
field in the job’s name
should be as simple as possible in order to be readable in the checks window.
Don’t be shy of using emojis.
Also, setup the run-name
field to show how and why the CI were triggered.
Typical workflows#
A typical project’s workflow should contain:
pre-commit checks: calls pre-commit
main tests: runs the main ctest
doc tests: runs other sphinx builders, e.g.
linkcheck
,html -W
static-analysis: in this template it is sonarcloud
code coverage: re-runs each subset of tests with coverage
release workflow: re-runs the CI tests, and publishes the release to GitHub and to other downstream packaging
[steps.[*].continue-on-error
]: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error