Where does the configuration go and what does a basic workflow actually look like?

GitHub Actions doesn't require you to install any separate software on your machine; it all lives in your repository. You need to create a specific folder hierarchy: .github/workflows/. Any YAML file you drop in there becomes a "workflow" that GitHub monitors.

I usually start with a simple file called ci.yml. If you're building an R package—let's imagine we're working on a package called tidyweather—you want the automation to trigger every time you push code or open a pull request. You don't want to manually run your test suite every five minutes; that's what the machine is for.

name: R-CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: r-lib/actions/setup-r@v2
      - name: Install dependencies
        run: Rscript -e 'install.packages(c("dplyr", "testthat"))'
      - name: Run tests
        run: Rscript -e 'testthat::test_local()'

Notice the r-lib/actions/setup-r step. This is the gold standard for R on GitHub. It handles the heavy lifting of getting R installed on the Ubuntu runner so you don't have to script the installation from source, which is a nightmare I wouldn't wish on anyone.

How do I ensure my package works across different R versions?

The "it works on my machine" excuse dies here. If you're distributing a package, you can't just test on R 4.3.1 and hope for the best. Some of your users might still be on 4.1 or already using a developmental version.

The trick is using a strategy matrix. This tells GitHub to spawn multiple virtual machines—one for each version you specify—and run the entire job on all of them simultaneously. It's incredibly satisfying to see a row of green checkmarks across four different R versions.

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        r-version: ['4.1', '4.2', '4.3', 'devel']
    steps:
      - uses: actions/checkout@v4
      - uses: r-lib/actions/setup-r@v2
        with:
          r-version: ${{ matrix.r-version }}
      - name: Check package
        uses: r-lib/actions/check_r_package@v2

I've switched from manual install.packages calls to r-lib/actions/check_r_package for most of my professional work. It does a full R CMD check, which catches things like missing documentation or incorrect namespace imports that a simple test_local() would miss.

What happens if the CI fails, and how do I stop bad code from merging?

When a workflow fails, GitHub marks the commit with a red 'X'. But the real power comes when you combine this with "Branch Protection Rules" in your repository settings. I always recommend enabling "Require status checks to pass before merging."

This effectively turns your CI into a gatekeeper. If you accidentally break a function in tidyweather and push it, the CI will fail, the red 'X' appears, and the "Merge" button on your pull request is physically disabled. You're forced to fix the bug before the code ever touches your main branch.

If you're seeing failures in CI that you can't replicate locally, check the logs in the "Actions" tab. Often, it's a missing system dependency (like libcurl or libssl). In those cases, you can add a step to install system packages using apt-get before the R setup step:

- name: Install system dependencies
  run: sudo apt-get update && sudo apt-get install -y libcurl4-openssl-dev libssl-dev

📋 Practical Task

Build a Multi-Version CI Pipeline for the "tidyweather" Package

You have been handed a repository for a package called tidyweather. Your goal is to implement a professional CI pipeline that prevents broken code from entering the main branch.

• Create a workflow file at .github/workflows/ci.yml.
• Configure the workflow to trigger on both push and pull_request events.
• Implement a strategy matrix that tests the package across R versions 4.1, 4.2, and 4.3.
• Use the r-lib/actions/setup-r action to initialize the R environment for each matrix version.
• Use the r-lib/actions/check_r_package action to run a full R CMD check on the code.

Verify your setup by pushing a change to a feature branch and ensuring the "Actions" tab in GitHub shows three separate jobs running in parallel.