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:

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

name: R-CMD-check
locale: caveman
source_locale: en
source_commit: 82c77053
translator: "Julius Brussee homage — caveman"
translation_date: "2026-04-19"

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 .github/workflows/R-CMD-check.yaml created with a multi-platform matrix (macOS, Windows, Ubuntu) covering release, devel, and oldrel.

On failure: If the .github/workflows/ directory does not exist, create it with mkdir -p .github/workflows. Verify YAML syntax with a YAML linter.

Step 2: Create Test Coverage Workflow (Optional)

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

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

name: test-coverage
locale: caveman
source_locale: en
source_commit: 82c77053
translator: "Julius Brussee homage — caveman"
translation_date: "2026-04-19"

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 }}

Expected: Workflow file .github/workflows/test-coverage.yaml created. Coverage reports will be uploaded to Codecov on each push and PR.

On failure: If Codecov upload fails, verify the CODECOV_TOKEN secret is set in the repository settings. For public repos, the token may be optional.

Step 3: Create pkgdown Deployment Workflow (Optional)

Create .github/workflows/pkgdown.yaml:

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

name: pkgdown
locale: caveman
source_locale: en
source_commit: 82c77053
translator: "Julius Brussee homage — caveman"
translation_date: "2026-04-19"

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

Expected: Workflow file .github/workflows/pkgdown.yaml created. Site builds and deploys to gh-pages branch on push to main or release.

On failure: If deployment fails, ensure the repository has contents: write permissions enabled. Verify _pkgdown.yml has development: mode: release set.

Step 4: Add Status Badge to README

Add to README.md:

[![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)

Expected: README displays a live CI status badge that updates automatically after each workflow run.

On failure: If the badge shows "no status," verify the workflow filename in the badge URL matches the actual file. Push a commit to trigger the first workflow run.

Step 5: Configure GitHub Repository Settings

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

Expected: GitHub Pages is configured for pkgdown deployment. Required secrets are set. Token permissions are sufficient for the workflows.

On failure: If Pages deployment fails, check Settings > Pages to ensure the source is set to the gh-pages branch. If secrets are missing, add them under Settings > Secrets and variables > Actions.

Step 6: Push and Verify

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 in the GitHub Actions tab. Workflows trigger on both push and PR events.

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

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