# Pathrule Pattern: GitHub Actions CI/CD (1.0.0)
# ::pathrule:package:github-actions-cicd

### [RULE] Least-privilege GITHUB_TOKEN by default  (path: /.github/workflows)
<!-- scope: folder | priority: high | strict -->

Every workflow must set explicit `permissions` instead of relying on the default read/write `GITHUB_TOKEN`.

- Set `permissions: {}` (or `contents: read`) at the workflow top level as a default-deny baseline.
- Grant scopes only on the individual jobs that need them, e.g. `packages: write` on the publish job only.
- Add `id-token: write` strictly on jobs that request an OIDC token, never workflow-wide.
- Set a `concurrency` group with `cancel-in-progress: true` so stale runs cannot push or deploy.

---

### [RULE] Pin every action to a full commit SHA  (path: /.github/workflows)
<!-- scope: folder | priority: high | strict -->

Reference every `uses:` action by a full-length 40-character commit SHA, with the human-readable version in a trailing comment.

- Write `uses: actions/checkout@<sha> # v6.0.0`, not `actions/checkout@v6` or `@main`.
- Pinning a mutable tag lets an upstream maintainer or attacker swap code under your runner with write access.
- First-party `actions/*` may pin to the major tag only if org policy allows it; all third-party and marketplace actions must be SHA-pinned.
- Keep pins current with Dependabot (`dependabot.yml` with `package-ecosystem: github-actions`) or `pin-github-action` so you get patched SHAs, not stale ones.

---

### [RULE] Cloud deploys authenticate via OIDC, not stored static keys  (path: /.github/workflows)
<!-- scope: folder | priority: high | strict -->

A long-lived cloud key stored as a CI secret is the highest-value, lowest-rotation credential most teams hold. Federate instead so the credential is minted per run and expires on its own.

- Grant the deploy job `permissions: id-token: write` and exchange the GitHub OIDC JWT for a cloud role. For AWS use `aws-actions/configure-aws-credentials` with `role-to-assume` and no `aws-access-key-id`/`aws-secret-access-key`. GCP and Azure have equivalent workload-identity federation actions.
- Lock the IAM trust policy to `repo:org/name` and constrain on `ref` or `environment` claims so only the intended branch or protected environment can assume the role.
- Bind the deploy job to a protected GitHub Environment with required reviewers; environment secrets are exposed only to that job.
- Note the immutable `sub` subject-claim rollout for new repositories (June 18 2026); pin trust conditions to claims that survive it.

---

### [MEMORY] Current GitHub Actions stack and caching defaults (2026)  (path: /.github/workflows)

These are the current stable building blocks for our pipelines as of mid-2026; do not downgrade them when editing workflows.

- Core actions: `actions/checkout@v6`, `actions/setup-node@v6`, `actions/cache@v5` (cache runs on Node 24 and needs runner >= 2.327.1).
- Prefer the built-in cache of `setup-node` (`cache: 'npm'`) over a manual `actions/cache` step for dependency restore.
- Reserve standalone `actions/cache` for build outputs (Turbo, Next, Playwright browsers) keyed on a lockfile hash with a partial `restore-keys` fallback.
- Test across versions with a matrix, e.g. `strategy.matrix.node: [20, 22, 24]`, and gate merges on the matrix job.
- Avoid `pull_request_target` with untrusted inputs in `run:` steps; an attacker can inject arbitrary shell commands via a PR title or body.

---

### [SKILL] github-actions-cicd-review  (path: /)

---
name: github-actions-cicd-review
description: Review checklist for GitHub Actions CI/CD workflows covering least-privilege tokens, SHA-pinned actions, OIDC deploys, caching, and matrix builds. Use when creating or editing any file under .github/workflows.
---

# GitHub Actions CI/CD review

- [ ] Workflow declares a top-level `permissions:` block that is default-deny (`{}` or `contents: read`).
- [ ] Write scopes (`packages`, `contents`, `id-token`, etc.) are granted per job, not workflow-wide.
- [ ] Every `uses:` references a full 40-char commit SHA with a `# vX.Y.Z` comment; no `@main` or floating tags.
- [ ] Dependabot or `pin-github-action` is configured to keep action SHAs current.
- [ ] Action versions are current: `checkout@v6`, `setup-node@v6`, `cache@v5` or newer.
- [ ] Dependency caching is enabled (`setup-node` `cache: 'npm'` or a lockfile-keyed `actions/cache`).
- [ ] Build matrix covers the supported runtime versions and merge protection requires the matrix job.
- [ ] Cloud deploys use OIDC (`id-token: write` + `role-to-assume`), with no long-lived keys in repo secrets.
- [ ] OIDC trust policy / `sub` claim is scoped to this repo and branch or environment.
- [ ] Deploy jobs target a protected GitHub Environment with required reviewers.
- [ ] A `concurrency` group with `cancel-in-progress: true` prevents overlapping deploy runs.
- [ ] `pull_request_target` triggers with untrusted-input `run:` steps are absent or carefully sandboxed.