rsc-universal 0.1.1

package/skills/github-actions/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: github-actions
+description: "Use when authoring or fixing GitHub Actions CI/CD — workflows under .github/workflows, jobs, the runner matrix, dependency caching, secrets and OIDC cloud deploys, environments and approval gates, reusable and composite workflows. Triggers: 'write a CI workflow', 'my GitHub Actions builds are slow / add caching', 'run the tests on a matrix of node versions', 'deploy to AWS without storing access keys' (OIDC), 'every push spawns a run and the old ones keep finishing' (concurrency), 'pin my actions / supply-chain hardening after the tj-actions thing', 'munta el desplegament continu amb GitHub Actions cap a producció', 'per què el GITHUB_TOKEN té permisos d'escriptura per defecte'. NOT writing the Dockerfile or image build strategy (that is docker), NOT the branching/merge model (that is git-workflow), NOT release readiness or the changelog (that is ship)."
+tags: [github-actions, ci-cd, workflows, oidc, caching]
+recommends: [docker, git-workflow, ship, deployment, secure-coding, aws-essentials, vercel]
+origin: risco
+---
+
+# GitHub Actions CI/CD
+
+A workflow is config that runs on an event. Before you write a single step, decide three things: **which events** fire the workflow, **what permissions** the token needs, and **where credentials come from**. Get those wrong and you have a fast pipeline that leaks secrets or a secure one nobody can trigger. Everything after that — checkout, install, test, build — is just steps.
+
+This skill owns the workflow layer: the `.github/workflows/*.yml` files, their triggers, jobs, matrix, caching, secret/OIDC handling, environments, and deploy gates. It does not own the image you build, the branching model, or the release decision (see the boundaries below).
+
+## Use this when
+
+- Writing or fixing a `ci.yml` / `deploy.yml` / `release.yml`.
+- Adding lint/test/build jobs on push or pull_request.
+- Speeding up CI with dependency caching.
+- Running a build across an OS x language-version matrix.
+- Wiring deploys: environments, approval gates, OIDC to a cloud, secrets.
+- Reusable workflows (`workflow_call`) and composite actions to kill copy-paste.
+- Killing redundant runs with `concurrency`; SHA-pinning actions for supply-chain safety.
+
+## Not this when
+
+- Authoring the `Dockerfile` or deciding the image build strategy → docker. The workflow may *call* `docker build`; designing the image is not this skill.
+- Branching model, PR hygiene, merge vs rebase, commit conventions → git-workflow.
+- Release readiness checklist, changelog, the shipping decision → `../ship/SKILL.md`.
+- Blue/green, canary, rollback *theory* → `../deployment/SKILL.md`. Actions triggers the deploy; the strategy is deployment's.
+- Choosing the host and its deploy primitives → `../vercel/SKILL.md` / `../aws-essentials/SKILL.md` / the host skill. Actions *triggers* the deploy; the host owns the target.
+- Triaging SAST/CVE findings or threat-modeling → `../secure-coding/SKILL.md`. This skill runs a scanner *as a job*; it does not interpret the report.
+
+## Decide the trigger first
+
+Pick the event(s) for each job class before writing YAML — the trigger decides what context and secrets the run gets.
+
+| Event | Use it for | Why |
+| --- | --- | --- |
+| `pull_request` | lint, test, build-check | Runs on the merge ref; from forks it gets **no secrets** (safe). |
+| `push` (to `main`) | deploy, publish artifacts, build the release | The trusted ref with full secrets/OIDC. |
+| `workflow_dispatch` | manual ops, one-off backfills, manual deploys | Human-triggered with inputs; auditable. |
+| `schedule` (cron) | nightly builds, dependency audits, cache warmers | Cron in UTC; no human in the loop. |
+| `release` / `push` tags | publish to a registry, cut a GitHub Release | Fires on the tag, not every commit. |
+| `workflow_call` | reusable workflow invoked by others | Library of jobs; never runs on its own. |
+| `pull_request_target` | label/comment bots that need write on forks | **Runs trusted with secrets** — never check out PR head here. |
+
+Do **not** run the same heavy job on both `push` and `pull_request` for the same commit — you pay runner minutes twice. Use `pull_request` for the checks and a separate `push: branches: [main]` job for deploy.
+
+## Anatomy of a CI workflow
+
+The minimal good CI: scoped trigger, read-only token, concurrency that cancels stale PR runs, built-in cache.
+
+```yaml
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read            # least privilege; widen per-job only when needed
+
+concurrency:
+  group: ci-${{ github.ref }}      # one run per branch/PR
+  cancel-in-progress: true         # newer push kills the stale run (PR feedback)
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6        # first-party, current major
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm                     # built-in lockfile-keyed cache
+      - run: npm ci                       # ci, not install — respects the lockfile
+      - run: npm run lint
+      - run: npm test
+```
+
+Rules baked into that file, each with its why:
+- `permissions: contents: read` at the top — **default token permissions may be write**; declare read-only and widen per job. A leaked write token can push tags or publish packages.
+- `concurrency` + `cancel-in-progress: true` — without it, every push to an open PR leaves the old run finishing and billing. One group per ref keeps at most one running + one pending.
+- `npm ci` not `npm install` — `ci` fails on a stale lockfile and is reproducible.
+- `actions/checkout@v6`, `setup-node@v6` — current majors (checkout v6.0.2, setup-node v6.4.0). Old majors run on Node 20, removed from runners in **September 2026**; JS actions are forced onto **Node 24** by default since June 2026. Upgrade to silence deprecation warnings and stay supported.
+
+## Caching
+
+Two mechanisms, in order of preference:
+
+1. **Built-in `cache:` on `setup-*`** — `setup-node`, `setup-python`, `setup-go`, etc. cache the package manager's store keyed on the lockfile. Free, one line. Use it.
+2. **`actions/cache@v4`** — for anything else (build output, custom tool dirs, compiled artifacts).
+
+The cache key is the whole game. A cache is **immutable once written for a key** — if your key never changes, you cache stale deps forever.
+
+```yaml
+# Bad — fixed key never invalidates; you restore yesterday's broken node_modules forever
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: npm-cache
+
+# Good — key changes when the lockfile changes; restore-keys gives a warm partial hit
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+    restore-keys: |
+      ${{ runner.os }}-npm-
+```
+
+`restore-keys` is a prefix fallback: an exact-key miss still restores the most recent cache whose key starts with the prefix, so a one-package change does not cold-start. Monorepo keys, Docker layer caching (`type=gha`), and runner-minute cost tradeoffs live in `references/caching-and-matrix.md`.
+
+## Matrix
+
+Run one job definition across combinations — OS x version is the common case.
+
+```yaml
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false            # see all combos' results, not just the first failure
+      max-parallel: 4
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        node: [20, 22, 24]
+        exclude:
+          - os: macos-latest      # don't pay the macOS multiplier on every version
+            node: 20
+        include:
+          - os: ubuntu-latest     # one extra cell: lint only on the canonical combo
+            node: 24
+            lint: true
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with: { node-version: "${{ matrix.node }}", cache: npm }
+      - run: npm ci && npm test
+```
+
+Set `fail-fast: false` when you want every combination's verdict (a compatibility matrix); leave it `true` (default) when one failure should abort the rest to save minutes. macOS and Windows runners bill at a multiple of Linux minutes — `exclude` the cells you do not need.
+
+## Secrets and OIDC — the security heart
+
+The rule: **no long-lived cloud keys in repo secrets.** Use OIDC. GitHub mints a short-lived JWT per run; AWS/Azure/GCP exchange it for a token scoped to that job, valid for minutes. Nothing static to steal — by 2026, static CI credentials are a compliance violation in regulated orgs.
+
+```yaml
+# Bad — static AWS keys live in the repo forever; one leak = standing access
+- uses: aws-actions/configure-aws-credentials@v4
+  with:
+    aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+    aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+
+# Good — OIDC: no stored keys, the role is assumed for this run only
+permissions:
+  id-token: write       # required for GitHub to mint the OIDC JWT
+  contents: read
+steps:
+  - uses: aws-actions/configure-aws-credentials@<full-40-char-sha>
+    with:
+      role-to-assume: arn:aws:iam::123456789012:role/gh-deploy
+      aws-region: eu-west-1
+```
+
+Hard rules:
+- **Never `echo` a secret** or pass it to an untrusted step. Secrets are masked in logs, but a third-party action or a crafted `printf` can exfiltrate them.
+- **Scope the cloud trust to repo + ref (+ environment).** The common 2026 misconfig is a trust policy with `repo:ORG/*` — that lets *any* repo in the org assume your prod role. Scope `sub` to `repo:ORG/REPO:ref:refs/heads/main` or `environment:production`.
+- **Gate prod with an `environment` + required reviewers** so a human approves before the deploy job runs.
+
+Per-cloud trust setup (AWS role, GCP Workload Identity Federation, Azure federated credentials), the over-permissioned-trust footgun, and a full deploy-on-tag workflow with approval are in `references/oidc-deploys.md`.
+
+## Supply chain and least privilege
+
+- **SHA-pin third-party actions to a full 40-char commit SHA, not a tag.** Tags are mutable: the **tj-actions/changed-files compromise (2025)** retargeted *all* tags to malicious code that dumped secrets. A SHA is the only immutable reference. GitHub now offers repo/org/enterprise policy to *enforce* full-SHA pinning across the whole tree.
+
+  ```yaml
+  # Bad — mutable tag; whoever controls the repo can repoint v1 at anything
+  - uses: some-org/some-action@v1
+  # Good — immutable, with a comment recording the human-readable version
+  - uses: some-org/some-action@a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0  # v1.4.2
+  ```
+
+  First-party `actions/*` and `github/*` may stay on a major tag (GitHub controls them), but pinning everything is the stronger posture.
+- **Keep `GITHUB_TOKEN` read-only by default**, widen per job. Set `permissions: contents: read` at the top, then grant exactly what a job needs (`packages: write` to publish, `id-token: write` for OIDC).
+- **`pull_request_target` + checking out the PR head = remote code execution with your secrets.** That trigger runs in the *base* repo's trusted context. If you then `checkout` `github.event.pull_request.head.sha`, you execute a fork's code with full secret access. Never combine them.
+
+## Reuse: workflow vs composite action
+
+Both kill copy-paste; pick by scope.
+
+| You need to reuse... | Use | Note |
+| --- | --- | --- |
+| whole jobs with their own `runs-on` / `services` / matrix | reusable workflow (`on: workflow_call`) | `secrets: inherit` to forward; set `concurrency` *inside* it. |
+| a set of steps that run inside one existing job | composite action | Lives at `.github/actions/<name>/action.yml`. |
+
+```yaml
+# caller — reuse a whole job
+jobs:
+  test:
+    uses: ./.github/workflows/reusable-test.yml
+    secrets: inherit
+```
+
+Gotcha: `concurrency` on the job that *calls* a reusable workflow does not behave as you expect — declare it inside the called workflow.
+
+## Deploy job pattern
+
+A deploy depends on the build, gets its own environment gate, and must **never** be cancelled mid-release.
+
+```yaml
+deploy:
+  needs: build              # only deploy a green build
+  runs-on: ubuntu-latest
+  environment: production   # required-reviewer gate lives on the environment
+  concurrency:
+    group: deploy-production
+    cancel-in-progress: false   # NEVER interrupt a release
+  permissions:
+    id-token: write
+    contents: read
+  steps:
+    - uses: actions/checkout@v6
+    - uses: aws-actions/configure-aws-credentials@<full-40-char-sha>
+      with:
+        role-to-assume: arn:aws:iam::123456789012:role/gh-deploy
+        aws-region: eu-west-1
+    - run: ./scripts/deploy.sh
+```
+
+`cancel-in-progress: false` here is the opposite of the CI default: cancelling a half-finished deploy can leave prod in a broken state.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Third-party action pinned to a tag (`@v1`) | tj-actions 2025: tags got repointed to secret-stealing code | Pin to a full 40-char SHA, comment the version |
+| `permissions: write-all` or no `permissions:` block | Default token may be write; a leak can push/publish | Top-level `contents: read`, widen per job |
+| Static cloud keys in repo secrets | Standing credentials; one leak = lasting access | OIDC `id-token: write` + `role-to-assume` |
+| OIDC trust scoped to `repo:ORG/*` | Any org repo can assume your prod role | Scope `sub` to repo + ref + environment |
+| No `concurrency` block | PR runs pile up and bill; deploys race | `cancel-in-progress: true` for CI, `false` for deploy |
+| Cache key with no lockfile hash | Restores stale deps forever (immutable per key) | `key: ...-${{ hashFiles('**/lock') }}` + restore-keys |
+| `pull_request_target` + checkout PR head | Runs fork code with your secrets (RCE) | Use `pull_request`; never check out untrusted head with secrets |
+| Same heavy job on `push` **and** `pull_request` | Double-bills runner minutes per commit | `pull_request` for checks, `push: [main]` for deploy |
+| `echo`-ing a secret to debug | Crafted steps/actions exfiltrate the masked value | Never print secrets; use OIDC short-lived tokens |
+
+## Verify
+
+After writing or editing workflows, run the static check on the repo:
+
+```bash
+skills/github-actions/scripts/verify.sh .
+```
+
+It globs `.github/workflows/*.{yml,yaml}`, runs `actionlint` if present, and independently flags unpinned third-party actions, missing `permissions:`, an OIDC nudge for jobs using cloud secrets, and the `pull_request_target` + PR-head footgun. It exits non-zero only on a hard error, so it works as a CI gate.

package/skills/github-actions/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — github-actions
+
+`cases.yaml` is a routing-and-capability spec, not an automated test runner. Read `should_trigger` / `should_not_trigger` as a judgement set: feed each prompt to the skill router and check it lands here for the trigger cases and routes to the named sibling (docker, git-workflow, ship, deployment, vercel) for the non-trigger cases — the non-obvious ones (caching by symptom, concurrency by symptom, OIDC instead of stored keys) are the ones worth watching. For `capability`, have the agent produce the hardened CI+deploy pipeline from the scenario and score it against the `must_include` rubric — every bullet should be present (SHA-pinned third-party actions, read-only default permissions, built-in cache, version matrix, gated OIDC deploy job, tuned concurrency). To sanity-check the artifact the skill emits, run `scripts/verify.sh <repo>` against a repo containing the generated workflows; it is read-only and exits non-zero only on a hard error.

package/skills/github-actions/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: github-actions
+
+should_trigger:
+  - prompt: "Set up CI to lint and test my Node app on every pull request."
+    why: "Core CI authoring — trigger, permissions, checkout/setup, lint/test job."
+  - prompt: "Our GitHub Actions builds take 9 minutes, mostly npm install — make them faster."
+    why: "Symptom-led, never names 'caching'; the fix is built-in setup-node cache / actions/cache."
+  - prompt: "Run the test suite against node 18, 20 and 22."
+    why: "Matrix build across language versions — strategy.matrix with fail-fast tuning."
+  - prompt: "Deploy to AWS from CI but I don't want to store AWS access keys in GitHub."
+    why: "Non-obvious: the answer is OIDC id-token:write + role-to-assume, not a secret."
+  - prompt: "Every push spawns a new run and the old ones keep finishing — stop the duplicates."
+    why: "Non-obvious symptom phrasing; the feature is concurrency with cancel-in-progress."
+  - prompt: "After the tj-actions thing I want to pin all our actions properly — how?"
+    why: "Supply-chain hardening — SHA-pinning third-party actions; oblique reference to the 2025 compromise."
+  - prompt: "Munta el desplegament continu amb GitHub Actions cap a producció amb aprovació."
+    why: "Catalan; continuous deploy to production with an environment approval gate."
+
+should_not_trigger:
+  - prompt: "Write a multi-stage Dockerfile for this service."
+    route_to: "docker"
+    why: "Image authoring and build strategy; the workflow may call docker build but does not design the image."
+  - prompt: "What branching strategy should we use, trunk-based or git-flow?"
+    route_to: "git-workflow"
+    why: "Branching/merge model is git-workflow, not the CI config layer."
+  - prompt: "Is this ready to release? Draft the changelog and decide the version bump."
+    route_to: "ship"
+    why: "Release readiness and changelog are the shipping decision, not workflow authoring."
+  - prompt: "Design a blue-green rollback strategy for our deploys."
+    route_to: "deployment"
+    why: "Deploy strategy theory (blue/green, canary, rollback) belongs to deployment; Actions only triggers it."
+  - prompt: "Configure the Vercel project's build command and environment variables."
+    route_to: "vercel"
+    why: "Host-side project configuration; the host owns the deploy target, Actions only triggers it."
+
+capability:
+  - scenario: "I have a Node 20 service in a GitHub repo. Give me a hardened CI + deploy pipeline that tests on a matrix of node versions and deploys to AWS on tag pushes without static credentials."
+    must_include:
+      - "First-party actions on current majors (checkout@v6, setup-node@v6); third-party actions pinned to a full 40-char commit SHA."
+      - "Top-level permissions set to contents: read, widened per job only where needed."
+      - "Built-in npm cache via setup-node (cache: npm) keyed on the lockfile."
+      - "A test job using strategy.matrix across multiple node versions."
+      - "A separate deploy job with needs: build and environment: production for the approval gate."
+      - "OIDC auth in the deploy job: permissions id-token: write plus role-to-assume, and no static AWS access keys in secrets."
+      - "concurrency groups: cancel-in-progress true for CI, false for the deploy/release job."

package/skills/github-actions/references/caching-and-matrix.md

@@ -0,0 +1,92 @@
+# Caching and matrix recipes
+
+Deep patterns for cache keys, Docker layer caching, matrix shaping, and runner-minute cost. The SKILL.md covers the common case; reach for this when a monorepo, a Docker build, or a large matrix makes the simple version waste minutes.
+
+## Cache keys beyond the simple case
+
+A cache entry is **immutable per key**. Once written, that key returns the same bytes until the key string changes. So the key must encode everything that should invalidate the cache.
+
+```yaml
+# Multiple lockfiles (monorepo) — hash all of them so any change rotates the key
+key: ${{ runner.os }}-deps-${{ hashFiles('**/package-lock.json', '**/pnpm-lock.yaml') }}
+restore-keys: |
+  ${{ runner.os }}-deps-
+```
+
+`restore-keys` is an ordered prefix-fallback list. On an exact-key miss, GitHub restores the newest cache whose key starts with the first prefix that matches, then the next, etc. That turns a "one dependency changed" cold start into a warm partial hit — you re-resolve only the delta.
+
+Per-workspace caches in a monorepo: put the package path in the key so each package gets its own entry instead of one giant shared cache that thrashes:
+
+```yaml
+key: ${{ runner.os }}-${{ matrix.pkg }}-${{ hashFiles(format('packages/{0}/package-lock.json', matrix.pkg)) }}
+```
+
+## Docker layer cache via buildx + gha backend
+
+For image builds inside a workflow, cache layers with the GitHub Actions cache backend (`type=gha`) so unchanged layers do not rebuild. The *image design* itself is the docker skill's concern — this is only the caching wiring.
+
+```yaml
+- uses: docker/setup-buildx-action@<full-40-char-sha>
+- uses: docker/build-push-action@<full-40-char-sha>
+  with:
+    context: .
+    push: false
+    cache-from: type=gha
+    cache-to: type=gha,mode=max
+```
+
+`mode=max` caches all layers (including intermediate build stages), not just the final image — bigger cache, far more hits on multi-stage builds.
+
+## Matrix shaping
+
+`include` adds cells or extra variables; `exclude` removes specific combinations. They compose: the matrix is built, `exclude` prunes, then `include` appends.
+
+```yaml
+strategy:
+  fail-fast: false
+  max-parallel: 6
+  matrix:
+    os: [ubuntu-latest, macos-latest, windows-latest]
+    node: [20, 22, 24]
+    exclude:
+      - { os: windows-latest, node: 20 }   # drop an unsupported combo
+      - { os: macos-latest, node: 20 }
+    include:
+      - { os: ubuntu-latest, node: 24, coverage: true }  # one cell does coverage
+```
+
+- `fail-fast: false` — every cell reports, even after one fails. Use it for compatibility matrices where you want the full grid of results.
+- `fail-fast: true` (default) — first failure cancels the rest. Use it to save minutes when any failure is a stop-the-line event.
+- `max-parallel` — cap concurrent cells when a shared resource (a test DB, a rate-limited API) cannot take the full fan-out.
+
+Dynamic matrix from a previous job (e.g. only the packages that changed): a setup job emits JSON via `$GITHUB_OUTPUT`, and the matrix consumes it with `fromJSON`:
+
+```yaml
+jobs:
+  discover:
+    runs-on: ubuntu-latest
+    outputs:
+      pkgs: ${{ steps.set.outputs.pkgs }}
+    steps:
+      - id: set
+        run: echo "pkgs=$(./scripts/changed-packages.sh)" >> "$GITHUB_OUTPUT"
+  test:
+    needs: discover
+    strategy:
+      matrix:
+        pkg: ${{ fromJSON(needs.discover.outputs.pkgs) }}
+    runs-on: ubuntu-latest
+    steps: [...]
+```
+
+## Runner-minute cost
+
+GitHub bills minutes by runner OS with a multiplier on hosted runners:
+
+| Runner | Relative cost |
+| --- | --- |
+| Linux (`ubuntu-latest`) | 1x — the baseline |
+| Windows | ~2x |
+| macOS | ~10x |
+
+So: do the bulk of the matrix on Linux, and only add macOS/Windows cells where the platform difference actually matters (native modules, platform-specific builds). `exclude` the cheap-to-skip combinations rather than running the full cartesian product on every OS. A matrix of `3 OS x 4 versions = 12` cells with a 10x macOS multiplier costs far more than `8 ubuntu + 2 macos + 2 windows` shaped with `exclude`.

package/skills/github-actions/references/oidc-deploys.md

@@ -0,0 +1,130 @@
+# OIDC cloud deploys (AWS / GCP / Azure)
+
+The goal: a deploy job assumes a cloud identity with **no stored long-lived keys**. GitHub mints a short-lived OIDC JWT for the run; the cloud provider validates it against a trust you configured and hands back a token scoped to that job for minutes. The job needs `permissions: id-token: write`.
+
+The recurring footgun across all three clouds is an **over-permissioned trust**: scoping it to `repo:ORG/*` (any repo in the org) instead of one repo + ref. Always pin the `sub` claim down to repo + ref, and for prod down to environment.
+
+## The OIDC `sub` claim — scope it tight
+
+GitHub puts the run's identity in the JWT `sub`. The cloud trust matches on it. Pick the narrowest that still works:
+
+| `sub` value | Grants to | Use for |
+| --- | --- | --- |
+| `repo:ORG/REPO:ref:refs/heads/main` | only `main` of one repo | branch deploys |
+| `repo:ORG/REPO:ref:refs/tags/v*` | tag pushes of one repo | release deploys |
+| `repo:ORG/REPO:environment:production` | the `production` environment of one repo | gated prod deploys (preferred) |
+| `repo:ORG/*` | **any repo in the org** | almost never — this is the footgun |
+
+Scoping to `environment:production` is strongest: the deploy only works from a job that names that environment, and the environment carries the required-reviewer gate.
+
+## AWS — IAM role + `configure-aws-credentials`
+
+One-time setup: create an IAM OIDC identity provider for `token.actions.githubusercontent.com`, then a role whose trust policy matches the `sub`.
+
+```json
+{
+  "Effect": "Allow",
+  "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" },
+  "Action": "sts:AssumeRoleWithWebIdentity",
+  "Condition": {
+    "StringEquals": {
+      "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
+      "token.actions.githubusercontent.com:sub": "repo:ORG/REPO:environment:production"
+    }
+  }
+}
+```
+
+In the workflow:
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+steps:
+  - uses: aws-actions/configure-aws-credentials@<full-40-char-sha>  # pin it
+    with:
+      role-to-assume: arn:aws:iam::123456789012:role/gh-deploy
+      aws-region: eu-west-1
+```
+
+## GCP — Workload Identity Federation
+
+Create a Workload Identity Pool + provider mapping `assertion.sub` to a principal, bind it to a service account.
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+steps:
+  - uses: google-github-actions/auth@<full-40-char-sha>
+    with:
+      workload_identity_provider: projects/123/locations/global/workloadIdentityPools/gh/providers/gh
+      service_account: gh-deploy@my-project.iam.gserviceaccount.com
+```
+
+Add an attribute condition on the provider so only your repo + ref can mint a token:
+`assertion.sub == 'repo:ORG/REPO:ref:refs/heads/main'`.
+
+## Azure — federated credentials
+
+On the app registration, add a federated credential with issuer `https://token.actions.githubusercontent.com`, subject `repo:ORG/REPO:environment:production`, audience `api://AzureADTokenExchange`.
+
+```yaml
+permissions:
+  id-token: write
+  contents: read
+steps:
+  - uses: azure/login@<full-40-char-sha>
+    with:
+      client-id: ${{ vars.AZURE_CLIENT_ID }}
+      tenant-id: ${{ vars.AZURE_TENANT_ID }}
+      subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+```
+
+`client-id`/`tenant-id`/`subscription-id` are identifiers, not secrets — keep them in `vars`, not `secrets`.
+
+## Full deploy-on-tag workflow with environment approval
+
+```yaml
+name: Release
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-production
+  cancel-in-progress: false      # never interrupt a release
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with: { node-version: 24, cache: npm }
+      - run: npm ci && npm run build
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: production        # required-reviewer gate; pauses here for approval
+    permissions:
+      id-token: write              # OIDC; no static keys
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - uses: aws-actions/configure-aws-credentials@<full-40-char-sha>
+        with:
+          role-to-assume: arn:aws:iam::123456789012:role/gh-deploy
+          aws-region: eu-west-1
+      - run: aws s3 sync dist/ s3://my-bucket --delete
+```
+
+The `environment: production` line is what makes GitHub pause for a reviewer before the deploy job starts — configure the required reviewers on the environment in repo settings, not in YAML.

package/skills/github-actions/scripts/verify.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# verify.sh — static lint for GitHub Actions workflows.
+# Read-only. No network, no install, no run. Heuristic and advisory.
+#
+# Checks .github/workflows/*.{yml,yaml} in the target dir:
+#   ERROR (exit 1): pull_request_target together with a checkout of the PR head
+#                   (runs untrusted fork code with full secrets).
+#   WARN: third-party uses: (not actions/* or github/*) not pinned to a 40-hex SHA.
+#   WARN: a workflow with no permissions: block (default token may be write).
+#   WARN: a step using secrets.AWS_/GCP_/AZURE_ creds while the file lacks id-token: write (OIDC nudge).
+# Runs `actionlint` if it is on PATH and surfaces its output.
+#
+# Exits non-zero ONLY on ERROR, so it works as a CI gate.
+# Exits 0 on a clean/empty target (no .github/workflows -> nothing to check).
+#
+# Usage: scripts/verify.sh [dir]   (defaults to current directory)
+set -euo pipefail
+
+DIR="${1:-.}"
+ERRORS=0
+WARN=0
+
+if [ ! -d "$DIR" ]; then
+  echo "verify.sh: '$DIR' is not a directory" >&2
+  exit 2
+fi
+
+err()  { echo "ERROR: $*"; ERRORS=$((ERRORS + 1)); }
+warn() { echo "WARN:  $*"; WARN=$((WARN + 1)); }
+
+WF_DIR="$DIR/.github/workflows"
+if [ ! -d "$WF_DIR" ]; then
+  echo "verify.sh: no .github/workflows under '$DIR' — skill not applied yet, nothing to check."
+  exit 0
+fi
+
+# bash 3.2 (macOS) friendly: newline-delimited list, no mapfile.
+FILES="$(
+  find "$WF_DIR" -maxdepth 1 -type f \( -name '*.yml' -o -name '*.yaml' \) 2>/dev/null
+)"
+
+if [ -z "$FILES" ]; then
+  echo "verify.sh: .github/workflows has no .yml/.yaml files — nothing to check."
+  exit 0
+fi
+
+# Optional: actionlint if available (advisory; its exit code does not gate us).
+if command -v actionlint >/dev/null 2>&1; then
+  echo "verify.sh: running actionlint..."
+  actionlint "$WF_DIR"/*.yml "$WF_DIR"/*.yaml 2>/dev/null || \
+    warn "actionlint reported issues (see above)."
+else
+  echo "verify.sh: actionlint not on PATH — running built-in checks only."
+fi
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+
+  # --- ERROR: pull_request_target + checkout of the PR head ---
+  if grep -Eq 'pull_request_target' "$f"; then
+    if grep -Eq 'github\.event\.pull_request\.head|head\.sha|head\.ref' "$f"; then
+      err "$f uses pull_request_target AND checks out the PR head — runs untrusted code with secrets (RCE). Use pull_request, or never check out head.* here."
+    fi
+  fi
+
+  # --- WARN: no permissions: block at all ---
+  if ! grep -Eq '^[[:space:]]*permissions[[:space:]]*:' "$f"; then
+    warn "$f has no permissions: block — the default GITHUB_TOKEN may be write. Set 'permissions: contents: read' and widen per job."
+  fi
+
+  # --- WARN: third-party uses: not pinned to a 40-hex SHA ---
+  # Lines like:  - uses: owner/repo@ref   (ignore ./local and docker:// forms)
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    ref="${line#*@}"                       # everything after the first @
+    owner="${line%%/*}"                    # owner segment of the action path
+    owner="${owner##*uses:}"
+    owner="$(echo "$owner" | tr -d ' ')"
+    # skip first-party actions/* and github/*
+    case "$owner" in
+      actions|github) continue ;;
+    esac
+    # accept exactly 40 hex chars (optionally followed by whitespace/comment)
+    if ! echo "$ref" | grep -Eq '^[0-9a-fA-F]{40}([[:space:]]|#|$)'; then
+      short="$(echo "$line" | sed -E 's/^[[:space:]]*-?[[:space:]]*uses:[[:space:]]*//' | cut -c1-60)"
+      warn "$f: third-party action not SHA-pinned: $short — pin to a full 40-char commit SHA (tags are mutable; cf. tj-actions 2025)."
+    fi
+  done <<EOF
+$(grep -E '^[[:space:]]*-?[[:space:]]*uses:[[:space:]]*[^./][^@]+@[^[:space:]]+' "$f" | grep -vE 'uses:[[:space:]]*\./|docker://' || true)
+EOF
+
+  # --- WARN: cloud secrets used but no id-token: write (OIDC nudge) ---
+  if grep -Eq 'secrets\.(AWS|GCP|GOOGLE|AZURE)[A-Z_]*' "$f"; then
+    if ! grep -Eq 'id-token[[:space:]]*:[[:space:]]*write' "$f"; then
+      warn "$f references cloud secrets (AWS/GCP/AZURE) but sets no 'id-token: write' — prefer OIDC over long-lived keys."
+    fi
+  fi
+done <<EOF
+$FILES
+EOF
+
+echo
+echo "verify.sh: $ERRORS error(s), $WARN warning(s)."
+[ "$ERRORS" -gt 0 ] && exit 1
+exit 0