Chapter 22 Using GitLab Continuous Integration

This is a generic template for R Markdown projcts. It does the following:

1. Download and initialize the “r-base” Docker package;
2. Update all installed software;
3. Download the PanDoc software;
4. In R, install the packge rmarkdown (as well as the dependencies);
5. Create a “public” directory;
6. Get the filename of the “.Rmd” file the “scripts” directory (taking the first one if multiple are encountered);
7. Use the rmarkdown R package to render that file to an HTML file called index.html in the “public” directory.

GitLab Pages automatically becomes available if a Continuous Integration stage called “pages” leaves artifacts in the “public” directory. Therefore, this CI configuration basically means that the rendered version of a project’s R Markdown file becomes available at the GitLab Pages URL correspondig to that project’s repository.

image: rocker/r-base

variables:
  APT_PKGS: "pandoc"

before_script:
  - apt-get update
  - apt-get install -y --no-install-recommends ${APT_PKGS}
  - R -e "install.packages('rmarkdown', repos='http://cran.rstudio.com')"

pages:
  stage: build
  script:
  - mkdir public
  - R -e "baseDir <- getwd(); rmdFile <- list.files(file.path(baseDir, 'scripts'), pattern='\\\\.Rmd', full.names=TRUE)[1]; rmarkdown::render(input=rmdFile, output_file=file.path(baseDir, 'public', 'index.html'));"
  - ls public
  artifacts:
    paths:
    - public
  only:
  - master

Note that you will often want to use other packages in your scripts, and it’s worthwhile to install those in the before_script section. Therefore, you may want to add more lines to that section. For example, this line installs the rmarkdown package:

  - R -e "install.packages('rmarkdown', repos='http://cran.rstudio.com')"

You could add this line to install the remotes package, that allows you to install packages directly from their git repositories:

  - R -e "install.packages('rmarkdown', repos='http://cran.rstudio.com')"

In case you want to then install a package directly from a git repository using the remotes package, you can also add something like:

  - R -e "remotes::install_gitlab('r-packages/ufs');"

By adding those commands to the CI configuration in the section that already install the rmarkdown package, these additional packages will also be available when the R Markdown script in rendered in the pages section.

If you have multiple R Markdown files, you can indicate that you always want the most recently changed one to render by replacing the line that starts with R -e in the pages stage with this:

  - R -e "rmdFiles <- fs::dir_info(here::here('scripts'), glob='*.Rmd'); rmdFile <- rmdFiles[order(rmdFiles[, 'modification_time']), 'path'][1]; rmarkdown::render(input=as.character(rmdFile), output_file=here::here('public', 'index.html'));"

In that case you’ll also need the here and the fs package, so add these lines to the before_script stage:

  - R -e "install.packages('here', repos='http://cran.rstudio.com')"
  - R -e "install.packages('fs', repos='http://cran.rstudio.com')"