Set Up GitHub Actions CI for R Packages

Configure automated R CMD check, test coverage, and documentation deployment via GitHub Actions.

When to Use

•Setting up CI/CD for a new R package on GitHub
•Adding multi-platform testing to an existing package
•Configuring automated pkgdown site deployment
•Adding code coverage reporting

Inputs

•Required: R package with valid DESCRIPTION and tests
•Required: GitHub repository (public or private)
•Optional: Whether to include pkgdown deployment (default: no)
•Optional: Whether to include coverage reporting (default: no)

Procedure

Step 1: Create R CMD Check Workflow

Create .github/workflows/R-CMD-check.yaml:

yaml

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

name: R-CMD-check

permissions: read-all

jobs:
  R-CMD-check:
    runs-on: ${{ matrix.config.os }}

    name: ${{ matrix.config.os }} (${{ matrix.config.r }})

    strategy:
      fail-fast: false
      matrix:
        config:
          - {os: macos-latest, r: 'release'}
          - {os: windows-latest, r: 'release'}
          - {os: ubuntu-latest, r: 'devel', http-user-agent: 'release'}
          - {os: ubuntu-latest, r: 'release'}
          - {os: ubuntu-latest, r: 'oldrel-1'}

    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
      R_KEEP_PKG_SOURCE: yes

    steps:
      - uses: actions/checkout@v4

      - uses: r-lib/actions/setup-pandoc@v2

      - uses: r-lib/actions/setup-r@v2
        with:
          r-version: ${{ matrix.config.r }}
          http-user-agent: ${{ matrix.config.http-user-agent }}
          use-public-rspm: true

      - uses: r-lib/actions/setup-r-dependencies@v2
        with:
          extra-packages: any::rcmdcheck
          needs: check

      - uses: r-lib/actions/check-r-package@v2
        with:
          upload-snapshots: true
          build_args: 'c("--no-manual", "--compact-vignettes=gs+qpdf")'

Expected: Workflow file created. Triggers on push/PR to main.

Step 2: Create Test Coverage Workflow (Optional)

Create .github/workflows/test-coverage.yaml:

yaml

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

name: test-coverage

permissions: read-all

jobs:
  test-coverage:
    runs-on: ubuntu-latest

    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

    steps:
      - uses: actions/checkout@v4

      - uses: r-lib/actions/setup-r@v2
        with:
          use-public-rspm: true

      - uses: r-lib/actions/setup-r-dependencies@v2
        with:
          extra-packages: any::covr, any::xml2
          needs: coverage

      - name: Test coverage
        run: |
          cov <- covr::package_coverage(
            quiet = FALSE,
            clean = FALSE,
            install_path = file.path(normalizePath(Sys.getenv("RUNNER_TEMP"), winslash = "/"), "package")
          )
          covr::to_cobertura(cov)
        shell: Rscript {0}

      - uses: codecov/codecov-action@v4
        with:
          fail_ci_if_error: ${{ github.event_name != 'pull_request' && true || false }}
          file: ./cobertura.xml
          plugin: noop
          token: ${{ secrets.CODECOV_TOKEN }}

Step 3: Create pkgdown Deployment Workflow (Optional)

Create .github/workflows/pkgdown.yaml:

yaml

on:
  push:
    branches: [main, master]
  release:
    types: [published]
  workflow_dispatch:

name: pkgdown

permissions:
  contents: write
  pages: write

jobs:
  pkgdown:
    runs-on: ubuntu-latest

    env:
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}

    steps:
      - uses: actions/checkout@v4

      - uses: r-lib/actions/setup-pandoc@v2

      - uses: r-lib/actions/setup-r@v2
        with:
          use-public-rspm: true

      - uses: r-lib/actions/setup-r-dependencies@v2
        with:
          extra-packages: any::pkgdown, local::.
          needs: website

      - name: Build site
        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
        shell: Rscript {0}

      - name: Deploy to GitHub pages
        if: github.event_name != 'pull_request'
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          clean: false
          branch: gh-pages
          folder: docs

Step 4: Add Status Badge to README

Add to README.md:

markdown

[![R-CMD-check](https://github.com/USERNAME/REPO/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/USERNAME/REPO/actions/workflows/R-CMD-check.yaml)

Step 5: Configure GitHub Repository Settings

•Enable GitHub Pages (Settings > Pages) pointing to gh-pages branch if using pkgdown
•Add CODECOV_TOKEN secret if using coverage reporting
•Ensure GITHUB_TOKEN has appropriate permissions

Step 6: Push and Verify

bash

git add .github/
git commit -m "Add GitHub Actions CI workflows"
git push

Check the Actions tab on GitHub to verify workflows run successfully.

Expected: Green checkmarks on all jobs.

On failure: Check workflow logs. Common issues: missing system dependencies (add to extra-packages), vignette build failures (ensure pandoc setup step is present).

Validation

• R CMD check passes on all matrix platforms
• Coverage report generates (if configured)
• pkgdown site deploys (if configured)
• Status badge shows in README
• Workflows trigger on both push and PR

Common Pitfalls

•Missing permissions: GitHub Actions now requires explicit permissions. Add permissions: read-all at minimum
•System dependencies: Some R packages need system libraries. Use r-lib/actions/setup-r-dependencies which handles most cases
•Vignettes without pandoc: Always include r-lib/actions/setup-pandoc@v2
•pkgdown development mode: Ensure _pkgdown.yml has development: mode: release for GitHub Pages
•Caching issues: r-lib/actions/setup-r-dependencies handles caching automatically

Related Skills

•create-r-package - initial package setup including CI workflow
•build-pkgdown-site - detailed pkgdown configuration
•submit-to-cran - CI checks should mirror CRAN expectations
•release-package-version - trigger deployment on release