r-ci

`r-ci`

Easy and portable CI for R packages

This repository provides a script run.sh for portable, flexible and lightweight Continuous Integration (CI) use at GitHub Actions, Travis, Azure Pipelines and Docker for local testing and use -- all shown below via real examples -- and likely others such as GitLab.

This script contains the following key functions which are typically all a user needs to call:

./run.sh bootstrap: Sets up the R environment, installs auxiliary packages such as testthat or tinytest.
./run.sh install_deps: Parses DESCRIPTION and installs the required packages. install_all is a (slightly heavier) alternative pulling not only dependencies but also suggested packages.
./run.sh run_tests: Builds the package tarball, and runs tests on it resulting in the overall CI test pass or fail.

See below for real examples

Use with GitHub Actions

GitHub Actions is currently en vogue and popular due to fairly unlimited build resources, along with the stunning own-goal scored by the previous incumbent. Usage with run.sh is easy. Just commit any file ending in .yml or .yaml in a directory .github/workflows within your GitHub repo---and you are all set. No additional registration is needed.

Below is an example .github/workflows/ci.yaml from the dang repository running a simple matrix build over Linux and macOS. Note that the matrix build for either can be turned off by placing a simple comment # character in front as can be seen in many example YAML files. Also note that this version now uses a small GitHub Action for r-ci-setup instead of the standard curl use shown in the other examples.


# Run CI for R using https://eddelbuettel.github.io/r-ci/

name: ci

on:
  push:
  pull_request:

env:
  _R_CHECK_FORCE_SUGGESTS_: "false"

jobs:
  ci:
    strategy:
      matrix:
        include:
          - {os: macOS-latest}
          - {os: ubuntu-latest}

    runs-on: ${{ matrix.os }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup
        uses: eddelbuettel/github-actions/r-ci-setup@master

      - name: Bootstrap
        run: ./run.sh bootstrap

      - name: Dependencies
        run: ./run.sh install_all

      - name: Test
        run: ./run.sh run_tests

Use with Travis CI

Travis CI continues to be useful for those with remaining free credits, or a paid plan, so very basic use by Open Source project on Linux should be unaffected.

The following code examples is an actual .travis.yml file, also from the dang repository used above. It runs a simple matrix build over macOS and Linux.


# Run CI for R using https://eddelbuettel.github.io/r-ci/

language: c
sudo: required
dist: focal

jobs:
  include:
    - name: linux
      os: linux
    - name: macOS
      os: osx

## Two core settings: BSPM for binary installation where possible, and no
## installation of 'Suggests:' to keep things lighter
env:
  global:
    - _R_CHECK_FORCE_SUGGESTS_="false"
      USE_BSPM="true"
    
before_install:
  - curl -OLs https://eddelbuettel.github.io/r-ci/run.sh
  - chmod 0755 run.sh
  - ./run.sh bootstrap

install:
  - ./run.sh install_all

script:
  - ./run.sh run_tests

after_failure:
  - ./run.sh dump_logs
 
#after_success:
#  - ./run.sh coverage

notifications:
  email:
    on_success: change
    on_failure: change

Use with Azure Pipelines

Azure Pipelines are an alternative worth considering as they also offer fairly generous usage credits. The example below is once again from the dang repository and is provided in its file .ci/ci.yaml (but in its git repo on Azure; these pipelines can also access other repos for example at GitHub). As in the other examples, a matrix over Linux and macOS is setup


# Evolved from starter pipeline via r-azure-pipelines repo

trigger:
- master

variables:
- name: R_LIBS_USER
  value: '$(Agent.BuildDirectory)/R/library'
- name: CRAN
  value: 'https://cloud.r-project.org'
- name: _R_CHECK_FORCE_SUGGESTS_
  value: false
- name: USE_BSPM
  value: true

strategy:
  matrix:
    linux:
      imageName: "ubuntu-latest"
    macos:
      imageName: "macos-latest"
  maxParallel: 2
  
steps: 
  - bash: curl -OLs https://eddelbuettel.github.io/r-ci/run.sh
    displayName: download
  - bash: chmod 0755 run.sh
    displayName: mode
  - bash: ./run.sh bootstrap
    displayName: bootstrap
  - bash: ./run.sh install_deps
    displayName: deps
  - bash: ./run.sh run_tests
    displayName: tests

Use with Docker

A key advantage of the simple run.sh script is its versatility: just drop it into a Docker session to test a local repo!

The following short video, part of post #32: Portable Continuous Integration using r-ci in the r^4 series of r^4 posts, demonstrates Docker use for CI with the dang repository used above.

The commands used in the video are, essentially, just these:


# launch docker using 'r-bspm:20.04' from rocker
docker run --rm -ti -v ${PWD}:/work -w /work rocker/r-bspm:20.04

# fetch the script
wget https://eddelbuettel.github.io/r-ci/run.sh && chmod 0755 run.sh

# bootstrap
./run.sh bootstrap

# install just depends
./run.sh install_deps

# test (with just depends)
export _R_CHECK_FORCE_SUGGESTS_="false"; ./run.sh run_tests

# alternate: install all
./run.sh install_all

# test (with all)
export _R_CHECK_FORCE_SUGGESTS_="true"; ./run.sh run_tests