| CARVIEW |
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, CircleCI as well as 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 bootstrapSets up the R environment, installs auxiliary packages such as
testthatortinytest. (Note that this step is included if you use ther-ciGitHub Action shown in the next example.)./run.sh install_depsParses
DESCRIPTIONand installs the required packages.install_allis a (slightly heavier) alternative pulling not only dependencies but also suggested packages../run.sh run_testsBuilds the package tarball, and runs tests on it resulting in the overall CI test pass or fail.
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 (adapted) example .github/workflows/ci.yaml from the RcppInt64 repository running a simple matrix build over Linux and macOS---and over two containers.
The containers offer, respectively, use of R-devel and a possibly slightly faster r2u setup (as times for this can vary at GitHub).
Note that the matrix build for any one of these 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 use the GitHub Action for r-ci
(instead of the standard curl use shown in the other examples)
which also includes the bootstrap step.
Lastly, one can uncomment the dumping of logs in case of failures, and
enable coverage as some of my repos do. (Note that you need to set a
repository secret under the name `CODECOV_TOKEN` with the supplied token string.)
For convenience this ci.yaml can also be downloaded.
# 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:
- { name: container, os: ubuntu-latest, container: rocker/r2u4ci }
- { name: r-devel, os: ubuntu-latest, container: rocker/drd }
- { name: macos, os: macos-latest }
- { name: ubuntu, os: ubuntu-latest }
runs-on: ${{ matrix.os }}
container: ${{ matrix.container }}
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Setup
uses: eddelbuettel/github-actions/r-ci@master
- name: Dependencies
run: ./run.sh install_all
- name: Test
run: ./run.sh run_tests
#- name: Logs
# run: ./run.sh dump_logs
# if: failure()
#- name: Coverage
# if: ${{ matrix.os == 'ubuntu-latest' }}
# run: ./run.sh coverage
# env:
# CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
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 CircleCI
CircleCI offers another alternative with a very polish browser interface and generous credits. The example below is again derived from the dang repository. It uses the r2u4ci container, fetches `run.sh` and uses it. The file has to be stored as `.circleci/config.yaml` in a repository registered at CircleCI.
version: 2.1
jobs:
ci:
docker:
- image: rocker/r2u4ci
steps:
- checkout
- run:
name: Download
command: curl -OLs https://eddelbuettel.github.io/r-ci/run.sh
- run:
name: Mode
command: chmod 0755 run.sh
- run:
name: Bootstrap
command: ./run.sh bootstrap
- run:
name: Dependencies
command: ./run.sh install_deps
- run:
name: Test
# set _R_CHECK_FORCE_SUGGESTS_="false" as needed
command: ./run.sh run_tests
workflows:
ci-workflow:
jobs:
- ci
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