CI Workflows

Purpose

Define what the repository CI workflows execute, what each workflow is expected to prove, and where each workflow fits in release evidence.

Audience

• Maintainers who triage CI failures and approve merges
• Reviewers validating release evidence
• Engineers who need to map local checks to CI outcomes

Workflow inventory

R-CMD-check.yaml

Trigger conditions

R-CMD-check.yaml runs on:

• push to main or master
• pull_request targeting main or master

Job contract

The workflow defines one matrix job named R-CMD-check with fail-fast: false across:

• macos-latest with R release
• windows-latest with R release
• ubuntu-latest with R devel
• ubuntu-latest with R release
• ubuntu-latest with R oldrel-1

Each matrix cell executes:

1. Repository checkout (actions/checkout@v4)
2. Pandoc setup (r-lib/actions/setup-pandoc@v2)
3. R setup (r-lib/actions/setup-r@v2)
4. Dependency resolution for checks (r-lib/actions/setup-r-dependencies@v2, needs: check, extra-packages: any::rcmdcheck)
5. Package check (r-lib/actions/check-r-package@v2) with:
   • build_args: c("--no-manual","--compact-vignettes=gs+qpdf")
   • upload-snapshots: true

What this job is expected to prove

• The package can be installed and checked on the supported CI matrix.
• R CMD check passes without check-level failures on each matrix cell.
• The package dependency graph in DESCRIPTION resolves in CI for each matrix cell.

What this job does not prove

• It does not run scripts/check.R --lint or scripts/check.R --style.
• It does not run runner smoke commands (scripts/dsambayes.R validate or run).
• It does not build or deploy pkgdown documentation.

pkgdown.yaml

Trigger conditions

pkgdown.yaml runs on:

• push to main or master
• pull_request targeting main or master
• release events where type is published
• Manual dispatch (workflow_dispatch)

Job contract

The workflow defines a single pkgdown job on ubuntu-latest with:

• Concurrency group pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
• Workflow-level permissions: read-all
• Job-level permissions: contents: write

The job executes:

1. Repository checkout (actions/checkout@v4)
2. Pandoc setup (r-lib/actions/setup-pandoc@v2)
3. R setup (r-lib/actions/setup-r@v2, use-public-rspm: true)
4. Website dependencies (r-lib/actions/setup-r-dependencies@v2, needs: website, extra-packages: any::pkgdown, local::.)
5. Site build (pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE))
6. Deploy step (JamesIves/github-pages-deploy-action@v4.5.0) only when event is not pull_request

What this job is expected to prove

• The pkgdown site can be generated from the current repository state.
• Package documentation inputs required by pkgdown are valid enough to build the site.
• On non-PR events, generated site output under docs/ can be pushed to gh-pages.

What this job does not prove

• It does not replace R CMD check as a package correctness gate.
• It does not execute full runner smoke tests.
• It does not provide release sign-off on its own.

Required secrets and permissions

• Both workflows set GITHUB_PAT from secrets.GH_PAT.
• R-CMD-check.yaml runs with read-only repository permissions (read-all).
• pkgdown.yaml requires contents: write in the pkgdown job to push to gh-pages.

If GH_PAT is absent, steps that require authenticated GitHub API access can hit stricter rate limits.

Expected logs and artefacts

R-CMD-check.yaml

Expected evidence in the GitHub Actions run:

• One job result per matrix cell
• check-r-package logs for each cell
• Clear pass or fail state per OS/R pair

pkgdown.yaml

Expected evidence in the GitHub Actions run:

• Build site log showing pkgdown generation status
• Deploy to GitHub pages log for non-PR events
• No deploy step execution for PR events

Failure handling

1. Treat any red CI job as a merge blocker until resolved or explicitly waived.
2. Reproduce failures locally with the nearest equivalent command:
   • R CMD check failure: run the rcmdcheck command from Quality Gates.
   • pkgdown build failure: run the pkgdown command from Quality Gates.
3. If failure is environment-specific (for example one matrix OS), capture that scope in the PR and link the failing job URL.
4. Re-run failed jobs only after a code or environment change that addresses the root cause.

Relationship to release gates

• R-CMD-check.yaml provides CI evidence for gate QG-4 in Quality Gates.
• pkgdown.yaml provides CI evidence for gate QG-7 in Quality Gates.
• Release sign-off still requires the full gate set and evidence bundle.