CI Guide

We use the R package tic to specify actions that should be executed on GitHub Actions.

tic

Why add another layer on top of GitHub Actions?

tic is ci-agnostic, meaning that the same script will also be valid on other CI systems (e.g. Appveyor for Windows).
tic makes the deployment of docs easy and transparent.
tic uses R functions instead of YAML defintions.
tic uses rcmdcheck::rcmdcheck() instead of R CMD CHECK. This enhanced version comes with the major among smaller advantages with the feature of showing the full log of failed tests.

In GHA YAML files most calls refer to specfic tic calls. These tic commands are then linked to definitions in tic.R. The organization of tic.R is similar to any CI/CD solution: It uses "stages", i.e. different levels of logical layers that are executed in a specific order (e.g. before_install runs before stage install).

tic.R is subdivided into groups by environment variables referring to specific build stages.

Initiating CI/CD on a new mlr3 repo

If you want to install GHA via tic in a new repo and build a pkgdown site, you need to ensure that the CI build is allowed to deploy to the repo. This can be ensured by calling tic::use_ghactions_deploy() and is always required to build the pkgdown site.

tic is able to auto-update itself by using a worfklow that runs once during the night. To set up this workflow, call tic::use_update_tic(). This workflow only works if there is a "secret" available called TIC_UPDATE which has scopes to update GitHub actions worfklows. To populate this secret, one needs to create a "Personal access token" with "workflow" scopes and add it to the repo via tic::gha_add_secret("<token>", "TIC_UPDATE").

To install the YAML workflow definitions, you can call tic::use_ghactions_yml() or copy over existing YAML files from other mlr-org repos. tic::use_ghactions_yml() will install a GHA workflow that runs R CMD Check on Windows, Linux and macOS and aims to build pkgdown site (which only works if tic::use_ghactions_deploy() has been called before).

Notifications of failed builds

As of today, only the account which set up a workflow initially gets notifications about failed builds. One can define whether these should appear as "GitHub notifications" alongside your GH feed or as emails (or both).

The setting can be found within the "Notfications" setting in your personal account.

Putting it all together

# add general R CMD Check workflow
tic::use_ghactions_yml()

# allow to deploy pkgdown site
tic::use_ghactions_deploy()

# ! Create PAT token with "workflow" scopes beforehand 
tic::gha_add_secret("<token>", "TIC_UPDATE")
tic::use_update_tic()