7  Continuous Integration

7.1 Understanding GitHub Actions

GitHub Actions is GitHub’s built-in automation platform that makes it easy to automate software workflows, including continuous integration and deployment (CI/CD). For R packages, this means you can automatically test your code, check for errors, and deploy documentation every time you push changes to GitHub.

Key benefits of GitHub Actions:

  • Automated testing: Run R CMD check across multiple operating systems (Linux, macOS, Windows) and R versions
  • Immediate feedback: Get notified of problems quickly, when they’re easier to fix
  • Better collaboration: External contributors can see if their changes pass all checks before you review
  • Quality assurance: Catch platform-specific issues before they reach users
  • Documentation deployment: Automatically build and deploy your pkgdown website

Even for solo developers, having automated checks run on different platforms helps avoid the “works on my machine” problem.

7.2 Setting Up GitHub Actions

The easiest way to add GitHub Actions to your R package is using {usethis}. The tidyverse team maintains a collection of ready-to-use workflows at r-lib/actions that handle common R package tasks.

7.2.1 Essential Workflows

1. R CMD check (most important):

usethis::use_github_action("check-standard")

This runs R CMD check on Linux, macOS, and Windows to ensure your package works across platforms. If you only set up one workflow, make it this one.

2. Test coverage:

usethis::use_github_action("test-coverage")

Calculates what percentage of your code is covered by tests and reports to codecov.io.

3. Package website:

usethis::use_github_action("pkgdown")

Automatically builds and deploys your pkgdown documentation site to GitHub Pages.

7.2.2 Interactive Setup

Running usethis::use_github_action() without arguments shows a menu of recommended workflows:

usethis::use_github_action()
#> Which action do you want to add? (0 to exit)
#> (See <https://github.com/r-lib/actions/tree/v2/examples> for other options)
#>
#> 1: check-standard: Run `R CMD check` on Linux, macOS, and Windows
#> 2: test-coverage: Compute test coverage and report to https://about.codecov.io
#> 3: pr-commands: Add /document and /style commands for pull requests

7.3 How GitHub Actions Workflows Work

When you set up a workflow, usethis creates a YAML configuration file in .github/workflows/. For example, check-standard creates .github/workflows/R-CMD-check.yaml.

This workflow automatically runs when you:

  • Push commits to main or master
  • Open or update a pull request

You can view workflow results in the “Actions” tab of your GitHub repository. A status badge is added to your README showing whether checks are passing.

7.4 Workflow Files and Security

Warning

Important Security Consideration

Workflow files (.github/workflows/*.yaml) have access to repository secrets and can execute code. Always review workflow files carefully before committing them, especially if copied from external sources.

See Section 18.5.8 for guidance on working with workflow files using AI tools.

The workflow YAML files in .github/workflows/ are configuration files that tell GitHub Actions:

  • When to run (on push, pull request, schedule, etc.)
  • What operating systems and R versions to use
  • What steps to execute (install dependencies, run checks, etc.)

7.5 Troubleshooting Failed Workflows

When workflows fail, check the “Actions” tab in your GitHub repository for detailed logs. Common issues include:

  • Test failures: Your tests found a bug (this is good! fix the bug)
  • Platform-specific issues: Code works on your machine but not on other platforms
  • Missing dependencies: System libraries needed for packages aren’t installed
  • Linting errors: Code style issues detected by automated checks

For help addressing workflow failures, see Section 18.5.6.

7.6 Pull Request Comment Automation

GitHub Actions can automatically comment on pull requests to provide feedback, status updates, or deployment previews. This section compares commonly used actions for managing PR comments, helping you choose the right tool for your workflow.

7.6.0.1 Common Use Cases

PR comment automation is particularly useful for:

  • CI/CD status updates: Report test results, build status, or deployment progress
  • Code quality reports: Post coverage reports, linting results, or security scan findings
  • Deployment previews: Share links to preview deployments (e.g., documentation sites, app previews)
  • Bot feedback: Provide automated feedback without cluttering the PR conversation

7.6.0.3 Feature Comparison

Comparison of PR comment action features
Feature marocchino/sticky hasura/comment-progress thollander/actions-comment
Update existing comment ✅ (by header) ✅ (by identifier) ✅ (by ID or content)
Multiple independent comments ✅ (via headers) ✅ (via identifiers) ⚠️ (limited)
Append mode ✅ ✅ ❌
Delete comments ✅ ✅ ✅
Hide comments ✅ ❌ ❌
File-based messages ✅ ❌ ❌
Emoji reactions ❌ ❌ ✅
Works with push events ✅ ⚠️ (requires PR number) ⚠️ (requires PR number)
Progress tracking focus ⚠️ (flexible) ✅ ❌

7.6.0.4 Choosing the Right Action

Use marocchino/sticky-pull-request-comment when:

  • You need to maintain multiple independent status comments (test results, coverage, deployment, etc.)
  • You want to prevent comment spam by updating the same comment
  • You need advanced features like hiding outdated comments or file-based templates
  • Your workflow triggers on push events and needs to find the associated PR

Use hasura/comment-progress when:

  • You have long-running workflows with multiple stages
  • You want to provide progressive feedback as each stage completes
  • You need the workflow to fail and report the failure in the comment
  • You want a pattern similar to third-party CI/CD service bots

Use thollander/actions-comment-pull-request when:

  • You need simple comment posting without complex update logic
  • You want to add emoji reactions to comments
  • You’re comfortable with the action’s simpler update mechanism
  • Your use case doesn’t require the advanced features of the other options

7.6.0.5 Security Considerations

Warning

Important: PR Comment Permissions

PR comment actions require write access to pull requests, which means they need the pull-requests: write permission.

For workflows triggered by pull requests from forks (common in open-source projects), be careful about what information you expose in comments, as fork contributors can trigger these workflows. Never expose secrets or sensitive information in PR comments.

See Section 18.5.8 for more guidance on workflow security.

7.7 Additional Resources