@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/cicd/github-actions/references/pipeline.md

@@ -0,0 +1,87 @@
+# Pipeline, lanes, and the required check
+
+> Read when: setting up CI in a new repo, choosing a merge queue, or a check is missing, stuck
+> "expected", or skipped.
+
+## Lanes
+
+```
+PR (non-draft) ──► PR lane: change-scoped checks ──► gate
+                    │
+   [optional merge queue: Mergify, GitHub merge_group, or none]
+                    ▼
+Queue candidate ──► queue lane: merged result + slow suites ──► gate
+                    ▼
+merge to main ────► Cloud Build: build → push by digest → migrate (if changed) → deploy dev
+                    ▼
+                  post-deploy lane (Actions): wait for Cloud Build's check on this SHA →
+                  confirm the serving revision is this SHA → smoke/e2e → status + incident issue
+                    ▼
+rc tag ───────────► Cloud Build: prod candidate at 0% traffic ──► rush-release verifies, shifts traffic
+```
+
+- **PR lane:** prove the change. Mergify admission < 2 min; no queue < 7 min (excluding E2E).
+- **Queue lane:** prove the merged result; run slow suites here. Mergify queue < 5 min
+  (excluding E2E). Without a queue, run slow suites on the PR and require an up-to-date branch.
+- **No main test lane with a queue:** the queue already tested the tree that lands on `main`;
+  a merge to `main` triggers deploy, not a CI rerun. Without a queue, `push: main` tests it.
+- **Post-deploy lane:** test the deployed revision, never a local build.
+  → [post-deploy-and-publishing.md](post-deploy-and-publishing.md)
+- **Scheduled lanes:** alert on failure (issue or chat ping).
+
+## Merge queue: optional, pick one
+
+| Option | When | Wire |
+|---|---|---|
+| **None** | Low PR volume, one author | Require `gate` + "require branch up to date". |
+| **Mergify** (most repos) | Batching, scopes, priorities | Candidates are draft PRs on `mergify/merge-queue/*` via `pull_request`. Let them through: `if: ${{ !github.event.pull_request.draft \|\| startsWith(github.head_ref, 'mergify/merge-queue/') }}`. Config: `mergify` skill. |
+| **GitHub native** | No third-party app | Add `on: merge_group:` to every workflow that reports `gate`. |
+
+Queue-only jobs: `if: startsWith(github.head_ref, 'mergify/merge-queue/')` (Mergify) or
+`if: github.event_name == 'merge_group'` (native). Make `gate` lane-aware.
+
+## The one required check
+
+Require exactly one check, `gate`, in branch protection and the queue. Template:
+[conditional-ci.md](conditional-ci.md#template).
+
+1. Put no `paths:` / `paths-ignore:` on a workflow that reports `gate`. Filter inside a
+   `changes` job.
+2. Give `gate` `if: always()` and `needs:` every job it covers.
+3. Skip area jobs, never `gate`. Allow a skip only for a named job whose condition was false;
+   fail on a skip caused by anything else (a missing secret, a failed dependency).
+4. Keep the name stable. Rename `gate` only together with the queue and branch-protection config.
+5. Put matrix and sharded jobs behind `gate`; never require a leg by name.
+
+## Workflow layout
+
+- Keep one `ci.yml` with the PR and queue lanes. Split files only by trigger:
+  `post-deploy.yml`, `nightly.yml`, `security.yml`, `publish.yml`.
+- Move repeated setup (install, Postgres start, workspace reset, container cleanup) into a
+  local composite action, `.github/actions/<name>/action.yml`.
+- Share across repos with a reusable workflow (`on: workflow_call`), called by a pinned ref,
+  never `@main`, with named secrets, never `secrets: inherit`.
+- Add `workflow_dispatch` where a manual re-run may be needed; guard it ([security.md](security.md)).
+
+## AI review jobs
+
+- Use a review bot to inform a merge, never as the only gate.
+- Never auto-pass a review gate on timeout.
+- Keep the trigger in one reusable workflow, not copied per repo.
+
+## New-workflow checklist
+
+- [ ] `permissions:` at top, `contents: read`
+- [ ] Every job has `timeout-minutes`
+- [ ] `concurrency` set; cancels only on PRs
+- [ ] No `paths:` on a workflow that reports `gate`
+- [ ] One `gate` job with `if: always()`; it is the only required check
+- [ ] Area jobs gate on `changes` outputs; `gate` allows a skip only when that filter was false
+- [ ] Non-E2E timings meet the SLA (Mergify admission < 2 min, queue < 5 min; else PR CI < 7 min)
+- [ ] Queue trigger handled (Mergify draft prefix or `merge_group`), if the repo uses a queue
+- [ ] Self-hosted: fork guard, canonical labels, `persist-credentials: false`, dynamic service ports
+- [ ] Third-party actions SHA-pinned (at least in jobs with secrets or `id-token`)
+- [ ] No `${{ }}` inside `run:`/`script:`; inputs go through `env:`
+- [ ] Missing secrets fail; no `continue-on-error` on tests
+- [ ] Schedules alert on failure
+- [ ] `actionlint` clean

package/skills/cicd/github-actions/references/post-deploy-and-publishing.md

@@ -0,0 +1,33 @@
+# Post-deploy verification and publishing
+
+> Read when: wiring tests that run after Cloud Build deploys, or a workflow that publishes a package.
+
+## Post-deploy verification
+
+After Cloud Build deploys dev, Actions verifies. There are two ways to start it.
+
+- **Preferred: poll Cloud Build's check run for the exact SHA** from a job triggered by
+  `push: main`. Don't rely on the `check_run` event: GitHub suppresses it for SHAs that
+  Actions already runs on. No Cloud Build → GitHub token needed.
+- **Alternative: `repository_dispatch`** from Cloud Build. The `event_type` must match
+  `on.repository_dispatch.types` exactly. Two repos send one name and listen for another.
+  A dispatch failure in Cloud Build must fail loudly, not `|| true`.
+
+Then:
+
+1. **Correlate.** Confirm the serving revision reports this commit (`/health` returns the SHA,
+   or the revision's env). Re-check after the tests; a newer deploy may have landed.
+2. **Target from an allowlist** keyed by environment name, never a URL from the payload.
+3. **One verdict step** that rolls up every step outcome. Never `continue-on-error` on the
+   tests themselves.
+4. **Report**: a commit status (`dev-post-deploy`), plus a deduplicated incident issue that
+   auto-closes on the next green run, plus a chat ping.
+5. **No concurrency cancellation** on this lane.
+
+## Publishing
+
+npm packages: trusted publishing (OIDC, no token): `environment: npm-publish`,
+`permissions: id-token: write`, the full verify suite first, an idempotency check (version
+already published? then assert its provenance matches this commit), a pack-contents check,
+publish, poll the registry until visible, then create the tag and release idempotently.
+Restrict to the default branch; pin the npm version; keep `contents: write` off the install step.

package/skills/cicd/github-actions/references/runners.md

@@ -0,0 +1,253 @@
+# Runners
+
+> Read when: adding or moving a job onto the self-hosted fleet, writing a job that starts its own
+> containers, a host process that needs a browser, or a job is queued and never starts. Source of truth for the fleet itself: the
+> `github-runner` repo (its README and `AGENTS.md`); change the fleet there, not in a workflow.
+
+## What a job actually gets
+
+Know this model before writing a step; most self-hosted failures come from assuming a
+GitHub-hosted VM.
+
+Fleet snapshot checked 2026-10-07: [runner README at 81f5dbd](https://github.com/1aboveio/github-runner/blob/81f5dbdd39da49b17addd7fd8f355257bc430224/README.md).
+Re-read the fleet contract and actual quota before tuning; these are defaults, not
+permission for a job to consume more than its assigned slot.
+
+| Property | Fleet | Consequence for the workflow |
+|---|---|---|
+| Runner | the official `actions-runner` image in a rootless Podman container, **ephemeral**: replaced after every job | no tool state carries between jobs; install what you need per job |
+| Workspace (`_work`) | **bind-mounted host disk, reused across jobs** | a fresh runner is not a fresh workspace: stale checkouts, `node_modules`, build output and git lock files can be there |
+| Size | configured default 8 CPUs / 16 GiB per slot, several slots per host | verify actual quotas; bound workers below the allotment and measure throttling/memory |
+| Network | host networking; all slots on a host share it | fixed ports collide between concurrent jobs |
+| `docker` | the host's rootless Podman API through `DOCKER_HOST` | `docker run`, `docker build` and `services:` work; native `container:` jobs do not reliably (below) |
+| Browsers | none in the runner image | Playwright runs in its own image; a host process gets a [wrapper](#a-host-process-that-needs-a-browser-binary) |
+| Package installs | npm, PyPI/uv index, Prisma engines and Docker Hub pulls go through LAN caches the runner injects; `uv sync --frozen` bypasses them | don't set registry env in workflows; install uv projects with `python-backend`'s `uv-install.sh` |
+| Capacity | one small pool shared by every repo in the org | every parallel job holds a slot another PR is waiting for |
+
+## Placement and labels
+
+Every slot carries `self-hosted, linux, x64, host, docker`; the fast host's slots add
+`premium`, the others add `general`.
+
+| Job | `runs-on` |
+|---|---|
+| Default (tests, builds, Postgres, Playwright) | `[self-hosted, linux, x64, docker]` |
+| Heavy or timing-sensitive (Spark, timing baselines) | `[self-hosted, linux, x64, docker, premium]` |
+| Needs Windows/macOS, or public/fork-facing | `ubuntu-latest` / `windows-latest` / `macos-latest` |
+
+- Spell labels lowercase, in this order, everywhere. A label no slot carries (a typo, a
+  retired per-host or per-slot label) queues the job forever, silently.
+- Target a class of runner, never a named slot or host. Slots are replaced constantly.
+- Ask for `premium` only when the job measurably needs it; it is the scarcest class.
+
+## Workspace: reused, so clean it
+
+- **Fork guard on every job**, before a runner is allocated. Fork code must never reach
+  our hosts:
+  `if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository`
+- **Wipe the workspace as the first step** when a job must not see a previous job's files
+  (anything that builds, installs, or globs the tree):
+  `ws="${GITHUB_WORKSPACE:?}"; find "$ws" -mindepth 1 -maxdepth 1 -exec rm -rf {} +`.
+- **Checkout with `persist-credentials: false`**; the token must not stay in `.git/config`
+  on a disk the next job reads.
+- Never write secrets, `.env` files or credentials files into the workspace; if a tool
+  insists, delete them in an `if: always()` step.
+- A checkout failing on `index.lock` or a `refs/*.lock` is a job killed mid-git on that
+  slot. The runner clears locks older than five minutes when it starts; a repeat is a
+  fleet bug to report, not a reason to add `rm .git/*.lock` to workflows.
+
+## Services and networking
+
+```yaml
+services:
+  postgres:
+    image: postgres:17
+    env: { POSTGRES_USER: test, POSTGRES_PASSWORD: test, POSTGRES_DB: app }
+    ports: ['5432/tcp']              # dynamic host port; never '5432:5432'
+    options: >-
+      --tmpfs /var/lib/postgresql/data:rw,noexec,nosuid,size=1g
+      --health-cmd pg_isready --health-interval 2s --health-timeout 5s --health-retries 25
+env:
+  DATABASE_URL: postgresql://test:test@127.0.0.1:${{ job.services.postgres.ports['5432'] }}/app
+
+```
+
+- **Dynamic ports only**, reached at `127.0.0.1` plus `job.services.<name>.ports[...]`.
+  Concurrent jobs on one host share its network, so a fixed port works in isolation and
+  fails under load.
+- **Give every service a health check** so steps start after it is ready. Poll every
+  1–2 s and raise the retries to keep the total timeout; a 10 s interval idles each job
+  for up to one interval after the service is ready.
+- **Put disposable databases on tmpfs, with a size.** Every slot on a host shares its
+  disks, so an on-disk scratch Postgres contends with every other job's I/O (slow
+  start, readiness probes timing out). tmpfs takes it off the disk: start-up went
+  13.5 s → 1.8 s ([case study](ci-case-studies.md)). Always set `size=`: tmpfs memory
+  comes from the slot budget, and an unbounded one can grow until the host swaps.
+  Example: `--tmpfs /var/lib/postgresql/data:rw,noexec,nosuid,size=1g` (raise it only
+  for a large seed). Same flag for `docker run`. The path is the image's `PGDATA`:
+  `postgres:18` and later use `/var/lib/postgresql`; a tmpfs on the old path leaves
+  the data on an anonymous disk volume.
+- **Keep durability on unless measured.** Disabling `fsync`, `synchronous_commit` and
+  `full_page_writes` is optional, only for disposable tests not proving
+  persistence/recovery, and only when measurement supports it; on tmpfs it added
+  no start-up benefit. The baseline above retains default durability. For an explicitly measured exception,
+  `services:` takes no server flags; use `ALTER SYSTEM` + reload, or pass
+  `-c fsync=off -c synchronous_commit=off -c full_page_writes=off` to `docker run`.
+- Don't depend on runner-specific names (`host.containers.internal`, a host's name, a
+  regional mirror). They differ per host and do not exist on GitHub-hosted runners.
+
+## Containers the job starts itself
+
+Native `container:` jobs make the runner auto-mount `/var/run/docker.sock` into the job
+container, which fails on this fleet before checkout
+(`statfs /var/run/docker.sock: permission denied`). Treat them as unsupported here; they
+remain fine on GitHub-hosted runners. Instead keep the job on the runner and `docker run`
+the tool image:
+
+```yaml
+- name: E2E in the Playwright image
+  run: |
+    docker run --name "e2e-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-${GITHUB_JOB}" --rm \
+      --network host --ipc=host --cpus 8 --memory 16g \
+      -e CI=true -e E2E_WORKERS=4 -e DATABASE_URL \
+      -v "${GITHUB_WORKSPACE}:/work:z" -w /work \
+      "${PLAYWRIGHT_IMAGE}" \
+      bash -lc 'npm ci && timeout 20m npx playwright test'
+- name: Remove the E2E container
+  if: always()
+  run: docker rm -f "e2e-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-${GITHUB_JOB}" 2>/dev/null || true
+```
+
+- **`--rm` is not cleanup.** It fires only when the container exits; a hung container never
+  exits and keeps a CPU busy after the job is cancelled (found on the fleet: two leaked
+  containers at ~100% CPU for 12 and 15 days). Name every container uniquely per run and
+  remove it in an `if: always()` step.
+- **Bound the command inside the container** (`timeout 20m …` in the container command),
+  never by wrapping the client (`timeout 20m docker run …`): killing the client detaches
+  the container, which then outlives the job.
+- **Stay inside the measured slot**: the current configured default is
+  `--cpus 8 --memory 16g`; use a lower cap when assigned one. Start Playwright at
+  `E2E_WORKERS=4`, not eight merely because eight CPUs are available, and drop to
+  `2` for a memory-heavy app. See [ci-case-studies.md](ci-case-studies.md) for why
+  worker increases need before/after evidence.
+- `--network host` so the container reaches `services:` at the same `127.0.0.1` port;
+  `:z` on the workspace mount for SELinux.
+- The fleet reaps CI containers older than about two hours. Keep every job well under that.
+- Playwright image and version matching: `e2e-test`'s `ci-playwright-container.md`.
+
+### A host process that needs a browser binary
+
+Sometimes the browser is launched by something that must stay on the runner: the app's own
+Backend rendering PDFs with Puppeteer (`executablePath`), started by an emulator or device
+harness that cannot move into a container. The runner has no browser, so the launch fails
+with "Browser was not found at the configured executablePath" (or missing `libnss3`/
+`libnspr4` if a binary is copied out of an image). Don't install Chromium on the runner,
+and don't copy the binary out of the image. Give the process a wrapper that runs the
+Playwright image's browser, and point the browser path variable at it:
+
+```yaml
+- name: Prepare host browser wrapper
+  id: host-browser
+  run: |
+    set -euo pipefail
+    # The image's own browser path, resolved by the repo's installed @playwright/test.
+    chrome=$(docker run --rm --pull=never --user "$(id -u):$(id -g)" \
+      -v "$PWD:/work:ro" -w /work "$PLAYWRIGHT_IMAGE" \
+      node -e 'process.stdout.write(require("/work/node_modules/@playwright/test").chromium.executablePath())')
+    case "$chrome" in /*) ;; *) echo "unresolved image browser: $chrome" >&2; exit 1 ;; esac
+    umask 077
+    dir=$(mktemp -d "$RUNNER_TEMP/host-browser.XXXXXXXX")
+    label="host-browser=${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+    {
+      printf '#!/usr/bin/env bash\nset -euo pipefail\n'
+      printf 'case "${TMPDIR:-}" in /*) ;; *) echo "needs an absolute TMPDIR" >&2; exit 1 ;; esac\n'
+      printf 'exec docker run --rm --init --pull=never --label %q --user %q --network host --ipc=host -e HOME="$TMPDIR" -v "$TMPDIR:$TMPDIR" %q %q "$@"\n' \
+        "$label" "$(id -u):$(id -g)" "$PLAYWRIGHT_IMAGE" "$chrome"
+    } > "$dir/chromium"
+    chmod 700 "$dir/chromium"
+    printf 'path=%s\nlabel=%s\n' "$dir/chromium" "$label" >> "$GITHUB_OUTPUT"
+- name: Journey
+  env:
+    CHROMIUM_PATH: ${{ steps.host-browser.outputs.path }}
+    TMPDIR: ${{ runner.temp }}/journey-tmp   # private, absolute; the wrapper shares only this
+  run: |
+    mkdir -m 700 -p "$TMPDIR"   # Puppeteer's mkdtemp fails on a missing TMPDIR
+    ./run-journey
+- name: Remove host browser containers
+  if: always() && steps.host-browser.outputs.label != ''
+  env:
+    LABEL: ${{ steps.host-browser.outputs.label }}
+  run: docker ps -aq --filter "label=$LABEL" | xargs -r docker rm -f
+```
+
+- **Why it works:** Puppeteer starts the "binary" (the wrapper), reads Chrome's
+  `DevTools listening on ws://127.0.0.1:<port>` line from stderr, and connects. With
+  `--network host` that port is the runner's loopback. Puppeteer keeps the profile in
+  `$TMPDIR`, so mounting that same path into the container at the same location is all
+  the host the browser sees. `--user` keeps the profile files owned by the runner user.
+- **Same version as the tests:** resolve the path through the repo's `@playwright/test`
+  inside the pinned image, the same way an in-container test would. A mismatch fails as
+  "not found", never silently.
+- **One label per run, cleaned in `always()`.** A normal `browser.close()` exits Chrome
+  and the container. A force-killed launch only kills the `docker` client and leaves
+  the container running, which is the `--rm`-is-not-cleanup trap above. You can't trap
+  SIGKILL in the wrapper, so remove containers by label after the step instead.
+- **Linux runners only.** On Docker Desktop (macOS), `--network host` does not reach the
+  Mac's loopback. Locally, Chrome starts and prints its endpoint, but the connection is
+  refused. Prove the wrapper in CI.
+- Use this for a process that has to stay on the host. When the whole tool can run in the
+  image (the test runner, a CLI check), put it in the image instead (above).
+
+## Resources, capacity and time
+
+- **Every job has `timeout-minutes`** sized to its lane; the fleet's longest planned
+  budget is a 35-minute browser lane. Self-hosted jobs do not get GitHub-hosted runners'
+  six-hour cap, so a hung step with no timeout holds a shared slot for hours to days
+  (jobs have been seen cancelled only after 24 hours).
+- **Parallel jobs cost the org, not just the PR.** The pool is shared; fanning one PR into
+  eight small jobs takes eight slots. Fold short static checks into one job (one checkout,
+  one install), and shard only where the wall-clock gain is real. `ci-run-audit.mjs` shows
+  both the setup share and the queue wait.
+- `concurrency: cancel-in-progress` on PR workflows frees slots from superseded pushes.
+
+## Packages and caches
+
+- The runner injects the npm, PyPI/uv and Prisma mirror settings, and Docker Hub pulls go
+  through a pull-through proxy. **Don't set `NPM_CONFIG_REGISTRY`, `PIP_INDEX_URL`,
+  `UV_DEFAULT_INDEX` or mirror hosts in workflows**: they break the same workflow on
+  GitHub-hosted runners and drift when the fleet changes.
+- **uv lockfile installs do not use that proxy on their own.** `uv sync --frozen` fetches
+  every package from the URL in `uv.lock` (`files.pythonhosted.org`) and ignores
+  `UV_DEFAULT_INDEX`. Install with the export + `uv pip sync --require-hashes` script from
+  `python-backend` (`assets/uv-install.sh`), then `uv run --no-sync`. Its
+  `references/uv-installs.md` also covers per-slot uv caches, toolcache vs uv-managed
+  Python, and trimming heavy packages.
+- Prefer the runner-local pnpm store over `actions/cache`; a network restore can cost more
+  than a cold install from the LAN mirror. Measure before adding a cache. uv's default
+  cache is in the ephemeral runner home, so it starts cold every job: point
+  `UV_CACHE_DIR` at the reused `_work` disk instead (`python-backend`'s
+  `references/uv-installs.md`).
+- Persist framework build caches (`.next/cache` and similar) the same way: in the
+  slot-local tool cache on the reused disk, one directory per lane, restored into the
+  checkout before the build. A fresh checkout otherwise rebuilds from cold every job.
+- Pin `postgres:17`, the Playwright tag and other images to a version, never `latest`,
+  so every slot runs the same thing and a bump is a reviewed one-line change.
+- `pnpm/action-setup` failing with `self-installer exits with code 1` before repo code runs
+  is a runner store-dir problem, not the repo's. Report it to the fleet.
+
+## When a job misbehaves
+
+| Symptom | Likely cause | Check |
+|---|---|---|
+| Queued, never starts | no online slot matches the label set, or every slot is busy | `gh api orgs/<org>/actions/runners --jq '.runners[] \| "\(.name) \(.status) \([.labels[].name] \| join(","))"'` |
+| Fewer slots online than usual | a host drained itself (its work disk went read-only) or the runner service is down | the fleet repo's health log; nothing to fix in the workflow |
+| Checkout fails on a `.lock` file | a previous job was killed mid-git on that slot | rerun once; report repeats |
+| `statfs /var/run/docker.sock: permission denied` | native `container:` job | switch to `docker run` (above) |
+| Service unreachable | fixed port, `localhost` name resolution, or no health check | dynamic port + `127.0.0.1` + `--health-cmd` |
+| `libnspr4.so` / missing browser libraries | Playwright running on the runner image | run it in the Playwright image |
+| `Browser was not found at the configured executablePath` | a host process (Puppeteer in the app's Backend) launches a browser the runner lacks | [host browser wrapper](#a-host-process-that-needs-a-browser-binary) |
+| Job fails only on one host | host drift (image, package or network helper versions) | note the runner name from the job log and report it with the run URL |
+
+Fleet problems (labels, lock files, stores, networking, capacity) are fixed in the
+`github-runner` repo and rolled to every host. A workflow that works around one hides it
+from every other repo.

package/skills/cicd/github-actions/references/security.md

@@ -0,0 +1,29 @@
+# Workflow security
+
+> Read when: writing or reviewing any workflow that holds secrets, writes, or runs on PR input.
+
+1. **`permissions:` at the top of every workflow**, `contents: read`; widen per job only
+   (`id-token: write` for OIDC, `issues: write` for an alert job, `statuses: write` for a
+   post-deploy verdict). A workflow with no block gets the repo default, often write-all.
+2. **Pin third-party actions to a full commit SHA** with the tag in a comment:
+   `uses: google-github-actions/auth@<40-hex sha> # v2.1.7`. Mandatory for any action in a job
+   holding secrets or `id-token: write`. Pair with Dependabot/Renovate for `github-actions` so
+   pins get updated (no repo has either today).
+3. **Never paste `${{ }}` into `run:` or `script:`.** Pass through `env:` and quote:
+   ```yaml
+   - env: { TARGET_SHA: "${{ github.event.client_payload.sha }}" }
+     run: git checkout "$TARGET_SHA"
+   ```
+   Applies to inputs, PR titles, branch names, dispatch payloads, and secrets.
+4. **Missing secret → fail, don't skip green.** A gate that silently passes when its
+   credential is absent proves nothing.
+5. **GCP from Actions: Workload Identity Federation**, never a JSON key. Least role, an
+   attribute condition on repo + workflow + ref, and delete the credentials file before
+   mounting the workspace into a container.
+6. **GitHub App tokens** (`actions/create-github-app-token`) over PATs for cross-repo writes
+   and dispatch. Cloud Build → GitHub dispatch: token from Secret Manager, scoped to one repo.
+7. **`pull_request_target`**: avoid. If unavoidable (for example, a queue bot's PR needs a
+   privileged check), verify the actor id and login and the branch prefix, check out as data
+   with `persist-credentials: false`, never run PR code, never expose secrets.
+8. **`workflow_dispatch` that can write**: reject non-default refs before any write job runs.
+9. **Deploy/publish jobs use `environment:`** so secrets are scoped and protection rules apply.

package/skills/cicd/github-actions/references/speed-and-audit.md

@@ -0,0 +1,115 @@
+# Auditing and speeding up CI
+
+> Read when: CI feels slow, or you suspect redundant jobs. Profile the bottleneck, optimize, then verify.
+
+The fix-first procedure is [audit-profile-optimize.md](audit-profile-optimize.md).
+Optional examples are in [ci-case-studies.md](ci-case-studies.md).
+
+## Inspecting CI
+
+Start with a representative successful run and identify the required-check critical path
+or runner-consumption bottleneck. Read that job and its commands first; expand to the
+workflow graph for parallelism, repeated setup, placement, or unnecessary work. Failures
+matter when they explain delays or block valid measurement, not merely because they are
+red. Expand history only for an unresolved symptom or an explicit audit.
+`scripts/ci-run-audit.mjs` reads through `gh`; it never edits workflows. Implement a
+justified scoped optimization, or stop with no change needed. Saving runs is optional:
+
+```bash
+node <github-actions>/scripts/ci-run-audit.mjs --repo <owner/repo> --profile-run <run-id> --json
+node <github-actions>/scripts/ci-run-audit.mjs --repo <owner/repo> --runs 60
+# Optional replay:
+node <github-actions>/scripts/ci-run-audit.mjs --repo <owner/repo> --runs 60 --save runs.json
+node <github-actions>/scripts/ci-run-audit.mjs --from runs.json --json
+```
+
+| Section | Finds | Typical fix |
+|---|---|---|
+| Re-proved trees | matching workflow/job run-tree metadata: PR → queue → main; tested checkout unverified | queue → main: drop the `push: main` trigger, don't build reuse; PR → queue: run each heavy check in one lane; changed queue trees still validate |
+| Catch yield | per job: failures, sole catches, flakes; jobs with no sole catch over 20+ code states | merge, move off the PR lane, or retire |
+| Overlap | a job whose every failure coincided with another job failing | read one log of each; merge or fix the shared fixture |
+| Setup share | jobs that are ≥70% overhead | fold them into one job |
+| Critical path | PR wait p50/p90 and which job finishes last | inspect that job's dependency chain; optimize the evidenced execution or scheduling bottleneck |
+| Stuck + queue | jobs past 6h; runner queue time | fix the runner; add `timeout-minutes` |
+
+Read it as candidates, not verdicts. A job with no catches may guard a rare, costly path
+(security, money); a date- or network-dependent job (quarantine expiry, live smoke) may
+repeat on the same tree on purpose. Pass `--ignore-job <regex>` for repo-specific roll-up
+jobs so they do not make every failure look shared. First org run (2026-09-27): four of
+seven repos spent 40–48% of passing job-minutes re-proving identical trees, and one had 14
+jobs hung for 24h.
+
+## Speed
+
+- **Caching.** GitHub-hosted: `setup-node` with `cache: pnpm`, `setup-uv` with
+  `enable-cache: true`. Self-hosted: prefer the runner-local pnpm store and uv cache over
+  `actions/cache`. A restore over the network measured 5m30s against a 21 s cold install.
+  Measure before adding a cache; `actions/cache` is remote, so on a LAN fleet it is
+  usually the wrong fix. Read each job's warm/cold status from its install log (the
+  store's reused-package count) before blaming downloads. With a LAN proxy and warm
+  per-slot stores, installs took 4–19 s; the rest was repeated work (duplicate type
+  checks, sequential DB prepare scripts, cold framework builds), not downloads.
+- **One type-check gate.** A framework build that type-checks (`next build`) inside every
+  test shard repeats the standalone, incremental `tsc` gate: 49 s × 5 shards plus 22 s in
+  the build job, against ~5 s for the gate. Disable the build's type check with a CI-only
+  flag in those jobs, keep the standalone gate required, and confirm its tsconfig covers
+  the same files. Never drop type checking from CI: local checks get skipped. Same for
+  lint-during-build versus a lint gate.
+- **Lockfile policy checks.** A supply-chain or policy check over the lockfile can be most
+  of the install (35–41 s, ~80%). Run it when the lockfile or its policy inputs differ
+  from an already-verified base, including in the queue when the batch changes them;
+  skip it on PRs whose lockfile matches base. Or give it a persistent metadata cache if
+  it supports one.
+- **Build once, fan out.** Build in one job, `upload-artifact` (with `include-hidden-files: true`
+  for `.next`), shard e2e with `--shard=${{ matrix.shard }}/N`, `fail-fast: false`, and roll up
+  in the gate.
+- **Timeout ladder.** Every job has `timeout-minutes`. Install budget < step timeout < job
+  timeout, with measured headroom for startup, diagnostics and cleanup between the inner
+  and outer limits. The job timeout is the only hang limit: the merge queue sets none
+  (`mergify` skill: `checks_timeout: null`). A job without
+  a timeout on a self-hosted slot can hold it for hours to days; self-hosted jobs lack
+  the six-hour cap GitHub-hosted jobs have.
+- **Concurrency.**
+  ```yaml
+  concurrency:
+    group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+    cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  ```
+  Never cancel deploy, publish, or post-deploy runs; builds can finish out of order.
+- **Retries** only in the queue lane, at most once, and log a `[flake-retry]` marker so a
+  pass-on-retry is visible. None on PRs.
+- **No redundant repeats.** Run each check once per tree: with a merge queue, drop
+  `push: main` and gate reruns on `schedule:` instead of building evidence reuse, and keep
+  a heavy check in one lane (PR or queue), not both. A changed queue tree still needs
+  validation. Build once and pass the artifact to dependent jobs.
+- **Workers.** Set the count from the slot size; `os.cpus()` inside a `--cpus 4` container
+  reports host cores. The values below are starting examples, not workers-equals-cores
+  policy; memory and shared fixtures can require fewer workers even with spare CPUs.
+  ```yaml
+  - env:
+      E2E_WORKERS: '4'        # playwright.config: workers: Number(process.env.E2E_WORKERS) || 4
+    run: pnpm exec playwright test
+  - run: pnpm vitest run --maxWorkers=4   # or: pytest -n 4
+  ```
+- **Disposable Postgres.** Size-bounded tmpfs by default (`size=1g`); it changes no
+  durability setting. Profile launch, readiness and schema preparation separately. Turn
+  durability off only when measured and not testing persistence/recovery. Poll health
+  every 1–2 s, not 10 s (a 10 s interval wasted ~15 s per job), with retries that keep
+  the total timeout. Many sequential SQL prepare scripts (27–49 s per job) are CPU and
+  round-trip bound, so tmpfs does not fix them: run them in one session, parallelize the
+  independent ones, or restore a snapshot keyed on a hash of the schema and prepare
+  inputs. [runners.md](runners.md#services-and-networking).
+- **Failure artifacts only.** Playwright: `screenshot: 'only-on-failure'`,
+  `trace: 'retain-on-failure'`, `video: 'off'`. Upload artifacts `if: failure()`.
+
+## SLA
+
+Excluding E2E jobs, measured push → `gate` result:
+
+| Setup | Lane | Budget |
+|---|---|---|
+| Mergify | PR admission | < 2 min |
+| Mergify | merge queue | < 5 min |
+| No queue | total PR CI | < 7 min |
+
+Over budget -> inspect the critical-path job, fix its cause, and verify the improvement.

package/skills/cicd/github-actions/references/two-pass-reading.md

@@ -0,0 +1,92 @@
+# Two-pass reading example
+
+Fetch what the parser needs; print only what the decision needs. These commands are
+read-only and create no report files. Run in Bash with Node, `gh`, `jq`, and the `yaml`
+Node package available (`node -e 'require("yaml")'` checks it). Use the repository's
+existing parser dependency; if absent, arrange it outside an audit-only target checkout.
+Do not parse workflow YAML with line-based regexes or execute workflow expressions.
+
+Set `SKILL_DIR` to the installed github-actions skill directory and fill in:
+
+```bash
+set -o pipefail
+REPO=owner/repo
+RUN=123456
+SHA=full-source-commit-sha
+WORKFLOW=.github/workflows/ci.yml
+```
+
+## Pass 1: Timings and job map
+
+Start with a representative successful run. Print one row per non-skipped job and its
+longest measured step, not the whole profile:
+
+```bash
+node "$SKILL_DIR/scripts/ci-run-audit.mjs" --repo "$REPO" --profile-run "$RUN" --json |
+  jq -r '
+    (["job", "runner", "created-to-start (s)", "execution (s)", "longest step", "step (s)"],
+     (.jobs | sort_by(.elapsedS // -1) | reverse | .[] |
+      select(.conclusion != "skipped") |
+      (.steps | map(select(.conclusion != "skipped" and .durationS != null)) |
+       max_by(.durationS)) as $step |
+      [.name, (.runnerName // "unknown"), (.queueS // "unknown"),
+       (.elapsedS // "unknown"), ($step.name // "unknown"),
+       ($step.durationS // "unknown")])) | @tsv'
+```
+
+For saved inputs, replace `--repo "$REPO"` with `--from /path/to/runs.json`. Null timings
+stay unknown; zero stays zero. Created-to-start is an observed scheduling interval, not
+proof of runner contention. Longest execution alone does not establish the critical path.
+
+Get a compact map from the pinned workflow using a YAML parser:
+
+```bash
+gh api "repos/$REPO/contents/$WORKFLOW?ref=$SHA" \
+  -H 'Accept: application/vnd.github.raw+json' |
+  node -e '
+    const fs = require("node:fs"), YAML = require("yaml");
+    const workflow = YAML.parse(fs.readFileSync(0, "utf8"));
+    if (!workflow?.jobs) throw new Error("Workflow has no jobs");
+    for (const [id, job] of Object.entries(workflow.jobs)) {
+      console.log(JSON.stringify({id, name: job.name ?? id,
+        needs: job.needs ?? [], if: job.if ?? null,
+        runner: job["runs-on"] ?? null, concurrency: job.concurrency ?? null}));
+    }'
+```
+
+Connect timings to this graph and the established required checks before picking the
+target. Job IDs are not display names; a matrix job may correspond to several timing
+rows. Read top-level concurrency separately if start delay makes it relevant. Do not
+assume the sampled run used this SHA: check source correspondence when needed.
+
+## Pass 2: Selected job and command
+
+Set `JOB` to an ID from the map (for example, `JOB=functional`). Print only that job's
+configuration; absent IDs fail visibly:
+
+```bash
+: "${JOB:?Set JOB to an ID from the map}"
+gh api "repos/$REPO/contents/$WORKFLOW?ref=$SHA" \
+  -H 'Accept: application/vnd.github.raw+json' |
+  node -e '
+    const fs = require("node:fs"), YAML = require("yaml");
+    const workflow = YAML.parse(fs.readFileSync(0, "utf8"));
+    const id = process.argv[1];
+    if (!Object.hasOwn(workflow?.jobs ?? {}, id)) throw new Error(`Unknown job: ${id}`);
+    process.stdout.write(YAML.stringify(workflow.jobs[id]));
+  ' "$JOB"
+```
+
+If that job is itself large, emit a step index first, then only the chosen step plus
+relevant job defaults. Follow its `run` command or local `uses` action to the invoked
+script and relevant function. Search function names to locate code; do not dump the
+whole repository tree. Expand to prerequisites, shared inputs, or selectors only when
+they affect the proposed change. Protect literal secrets/private URLs before printing.
+
+Stop when a bounded optimization is justified, or name the single missing check:
+
+> Start delay dominates, but its cause is unknown. Check whether eligible runner slots
+> or the concurrency lock were occupied. No workflow patch is justified yet.
+
+The same distinction applies to caching: visible install cost is an opportunity, not
+predicted savings; restore/install/save cost determines whether the candidate pays off.