CI Guide

In the past, most mlr3 packages relied on tic to specify the CI actions. This has mostly been replaced by configuring the CI workflows in pure yaml. Predefined workflows that can be adjusted to the need of the specific package, can be found in the actions repository of the mlr-org.

Below you can find some information about tic.

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.

pkgdown URL

To create pkgdown urls in the form of <pkgname>.mlr-org.com we need to create a CNAME entry in the DNS zone of mlr-org.com This can be done by Patrick, Michel or Bernd and unfortunately we cannot add more people as the free plan from Netflify only allows three people. Hence, please write one of the three (preferred Patrick or Michel) and ask them to add a CNAME entry for a new mlr3package.

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()