14 Github Workflows

Github Actions allows for a series of automated workflows that are very handy when it comes to publishing R packages, as well as other more general CI/CD work.

This chapter explains the most common workflows used across the PIP project. Other example workflows can be found here.

14.1 Package webpage using `{pkgdown}`

pkgdown makes it easy to build websites for R packages. With a Github Action workflow this is made even easier because the website will be built and published automatically everytime you commit to the master (main) branch. There is thus no need to run pkgdown::build_site() yourself.

14.1.1 Create `gh-pages` branch

The most common is for a {pkgdown} site to live in a seperate branch in your repository called gh-pages. This should be an empty orphan branch, with no files or commits other then the inital root commit.

Some {usethis} helpers claims to create this branch for you, but this doesn’t always work. Follow the steps to below to create an empty branch manually.

# Create new orphan branch 
git checkout --orphan gh-pages
# Remove everything
git rm -rf .
# Create empty commit
git commit --allow-empty -m "root commit"
# Push to remote
git push origin gh-pages
# Switch back to master
git checkout master

14.1.2 Create “setup” files

Create a new local branch in your repository, and then take advantage of the helper functions in the {usethis} package. Run this from the working directory of your local branch:

usethis::use_pkgdown_github_pages()

This should create the entire setup needed, including adding the files _pkgdown.yml and .github/workflows/pkgdown.yaml to your working directory.

Create a pull request and merge the changes to the master branch.

14.1.3 Activate Github Pages

Go to Settings -> Github Pages. Activate Github Pages and set it to build from gh-pages/root.

Remember to also add your page link to the About section of your repo.

14.2 Package build checks

A crucial part of any R package development process is the build check.

With Github Actions you can add workflows to automatically check your package for different versions of R and on different operating systems. A good way to get started is to use the simple release workflow, but more advanced packages will benefit from a standard or custom workflow.

A standard workflow checks if the package builds on the latest available R version on all three major operating systems (Windows, macOS, Ubuntu), and should be used for all packages that are planned to be published on CRAN. A custom workflow is helpful if you want to check your package against specific versions of R or other OS variants.

For the current PIP R packages both {wbpip} and {pipapi} go through a standard build check, while other packages have custom workflows. For example do the build checks for {pipaux} and {pipdm} test if the package works for the latest version of R and the current R version on the PovcalNet remote server.

14.3 Code coverage

Another important part of package development is to check the code coverage of your unit tests. This is typically done with the {covr} package.

With Github Actions you can automatically upload coverage reports to codecov.io, to let yourself and others more easily keep track of the test coverage of your package.

14.3.1 Create “setup” files

Create a new local branch in your repository, and then take advantage of the helper functions in the {usethis} package. Run this from the working directory of your local branch:

usethis::use_coverage("codecov")
usethis::use_github_action("test-coverage")

This should create the entire setup needed, including adding the files codecov.yml and .github/workflows/test-coverage.yaml to your working directory.

Create a pull request and merge the changes to the master branch.

14.3.2 Integrate with codecov.io

All the repositories are already synced with codecov.io, so you only need to make sure all your test are passing and push to GH to activate your test coverage.

14.4 Other workflows

The PR commands workflow enables the use of two specific commands in pull request issue comments. /document will use roxygen2 to rebuild the documentation for the package and commit the result to the pull request. /style will use styler to restyle your package.

14.1 Package webpage using {pkgdown}

14.1.1 Create gh-pages branch