Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -348,6 +348,11 @@ jobs:
- name: E2E quarantine lane tests
run: python3 scripts/test_e2e_quarantine.py

# The v3 composite actions (actions/): actionlint and lint_callables.py read only .github/workflows, so this is
# the one check that sees them. It runs each step's shipped script, and shellcheck over it.
- name: Composite action tests (v3)
run: python3 scripts/test_actions.py

# Cheap belt-and-braces: actionlint parses YAML itself, but a file it
# cannot classify as a workflow is skipped rather than failed, so an
# unparseable stray .yml would slip past both checks above.
Expand Down
6 changes: 5 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@ public; its own CI and every public caller must use GitHub-hosted runners.
Private callers retain their existing reusable-workflow access and may use
manifest-routed self-hosted capacity where their repository policy permits it.

v3 is four composite actions under [`actions/`](./actions/README.md) (`setup`,
`verify`, `version-proof`, `health`): steps a caller's own job uses, with no
runner input and no `Required` job. `scripts/test_actions.py` is their gate.

The estate-wide operating manual for agents lives in
[narduk-enterprises/agent-infrastructure](https://github.com/narduk-enterprises/agent-infrastructure)
(its root `AGENTS.md`). On the Macs it is loaded automatically; in a cloud
Expand All @@ -30,7 +34,7 @@ container nothing loads it for you — read it first, then return here.
|---|---|
| What is this repo? | The estate's shared reusable Actions workflows, consumed via `workflow_call` |
| Estate operating manual | [narduk-enterprises/agent-infrastructure](https://github.com/narduk-enterprises/agent-infrastructure) → `AGENTS.md` |
| Run the checks | `actionlint -no-color -oneline .github/workflows/*.yml`, `python3 scripts/lint_callables.py`, then each `python3 scripts/test_*.py` |
| Run the checks | `actionlint -no-color -oneline .github/workflows/*.yml`, `python3 scripts/lint_callables.py`, then each `python3 scripts/test_*.py` (`test_actions.py` alone covers `actions/`) |
| Catalog, consumption, versioning | [`README.md`](./README.md) — what each callable does, how to call it, how tags move |
| Structural rules (R1–R13) | [`scripts/lint_callables.py`](./scripts/lint_callables.py) — the rule table at the top |
| Cloud-session setup | [narduk-enterprises/agent-infrastructure](https://github.com/narduk-enterprises/agent-infrastructure) → `docs/cloud-sessions.md` |
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,10 @@ in their app-class workflow.
| `flake-digest.yml` | **New 2026-09-24** (narduk-reboot P3-C2). Weekly, advisory: scans a caller's completed runs of one workflow, counts failures in jobs matching `quarantine-job-pattern` (nuxt-cloudflare.yml's `e2e-quarantine` by default), and files or refreshes one digest issue per ISO week. Never gates `main`, never opens `red-main` |
| `taskgraph.yml` | **New 2026-10-29.** Vercel CI's model (beta 2026-10-28) for any `package.json`-script repo: the caller's `turbo.json` tags the CI tasks, each task gets a content key from Git's blob hashes, a task whose key already passed is never run again (GitHub's own record of a green run of the same content, with no secret; per task, a pointer in the R2 CI artifact store that GitHub's API must confirm), `FAST_BASE_REF` scripts run narrowed on PRs keyed on their base, and the rest run side by side after one install per machine, each in its own worktree; a `ci:machine` task gets its own seat. Plan, Tasks legs, Required, and a `Fast` alias of Required's real result for rulesets that still require `ci / Fast`; nine inputs. See [taskgraph.yml](#taskgraphyml) |

**v3 (2026-11-17) is composite actions, not more callables:** `setup`, `verify`, `version-proof` and `health` under
[`actions/`](./actions/README.md). A caller keeps its own jobs and uses them as steps, so there is no `runner` input, no
`Required` job and nothing here to route. New work starts there; the callables above keep their callers.

All eleven shipped callables are `on: workflow_call` only — none of them declare their own
triggers, and none declare workflow-level `concurrency:` (see "How to consume"
below for job-level cancellation and the caller's workflow group).
Expand Down
76 changes: 76 additions & 0 deletions actions/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# v3: composite actions

Four steps a repository's own workflow calls. They are composite actions, not reusable workflows, on purpose:

- **The caller keeps its jobs.** A reusable workflow brings its own jobs, runner choice and a `Required` job that takes a
runner to add up the others. A composite action is steps inside the caller's job: the caller owns `runs-on`, `if`,
`needs`, `permissions`, `concurrency` and the check's name, and no job exists only to report on other jobs.
- **Nothing to route.** No `runner` input, no organization variable, no visibility test. The job that uses the action
already says where it runs.
- **Small enough to read.** Each is one file under 80 lines, or one script; `scripts/test_actions.py` runs the shipped
text of every step.

They come from PACC·TRAC's CI after it was cut from six jobs per pull request to one (2026-11-17). v1 and v2 (the
reusable workflows in `.github/workflows/`) are unchanged and keep their callers.

| Action | What it does | Inputs |
| --- | --- | --- |
| [`setup`](./setup/action.yml) | Node from `.node-version`, pnpm from `packageManager`, the pnpm store where the runner can keep it, `pnpm install --frozen-lockfile` | `node-version-file`, `install-args` |
| [`verify`](./verify/action.yml) | Runs the checks `Config/remote-gate.json` names: what the diff selects on a pull request, the whole list otherwise; side by side, one timed line each | `scope`, `alone`, `config`, `base` |
| [`version-proof`](./version-proof/action.yml) | Polls a URL until it answers this commit's SHA; red when it never does | `url`, `expected`, `attempts`, `interval` |
| [`health`](./health/action.yml) | Polls a health URL until it answers 200; red, with the body, when it never does | `url`, `attempts`, `interval`, `means` |

## A caller

```yaml
jobs:
verify: # the one required check: on a pull request and on main
runs-on: <the repository's own route>
timeout-minutes: 20
permissions:
contents: read
steps:
- uses: actions/checkout@<sha> # v7
with:
fetch-depth: 2 # a pull request is compared with HEAD^1: that commit must be present, older history need not be
persist-credentials: false
- uses: narduk-enterprises/workflows/actions/setup@<sha> # v3
- uses: narduk-enterprises/workflows/actions/verify@<sha> # v3
with:
alone: typecheck-demo build

deploy-staging:
needs: [verify, build]
steps:
# ... the repository's own deploy ...
- uses: narduk-enterprises/workflows/actions/version-proof@<sha> # v3
with:
url: https://staging.example.com/version
- uses: narduk-enterprises/workflows/actions/health@<sha> # v3
with:
url: https://staging.example.com/healthz?deep=1
means: the database binding or its migrations are wrong
```

Pin the full commit SHA `v3` points to, with a `# v3` comment, as for v2. Never `@main`.

A repository whose checks read history itself (old commits, their trees) needs `fetch-depth: 0`; give it
`filter: blob:none` as well. Full history with every old file's contents was PACC·TRAC's longest step in this job (28 s
at the median, up to 653 s, 2026-11-17); without the contents the same checkout took 4 to 10 s.

## The gate file

`verify` reads the same `Config/remote-gate.json` that `remote-gate --changed` reads on a developer's machine
(agent-infrastructure `scripts/remote_gate.py`), so a change that is green there runs the same checks in CI:

- `checks`: name to shell command. `{files}` becomes the changed files a rule matched; `{base}` the base commit.
- `default`: the names every event but a pull request runs.
- `changed.rules`: `paths` (globs from the repository root) to `checks`; `changed.always`: names every pull request
runs; `changed.full`: paths that swap one check for another (the changed-files lint for the whole lint).

`alone` is the action's own input, not part of the file: the checks that must not share memory with the rest.

## What is not here yet

The build with its byte-exact handoff to the deploy, the deploy itself (migrate, read the ledger back, `wrangler deploy`)
and the browser sweep are still PACC·TRAC's own steps. They move here when a second repository needs them.
41 changes: 41 additions & 0 deletions actions/health/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
name: Health probe
description: >-
Ask a health URL until it answers 200, and fail with the first 600 bytes of its last answer when it never does.
For the deep probe after a deploy: the code is proven by version-proof, this proves what it is bound to.

inputs:
url:
description: The URL to probe, e.g. https://staging.example.com/healthz?deep=1.
required: true
attempts:
description: How many times to ask.
default: '10'
interval:
description: Seconds between attempts.
default: '5'
means:
description: What a failure means, for the error line, e.g. "the D1 binding or its migrations are wrong".
default: ''

runs:
using: composite
steps:
- name: Probe the health URL
shell: bash
env:
HEALTH_URL: ${{ inputs.url }}
HEALTH_ATTEMPTS: ${{ inputs.attempts }}
HEALTH_INTERVAL: ${{ inputs.interval }}
HEALTH_MEANS: ${{ inputs.means }}
run: |
set -uo pipefail
body="$(mktemp)"; trap 'rm -f "$body"' EXIT
for i in $(seq 1 "$HEALTH_ATTEMPTS"); do
code=$(curl --silent --max-time 15 -o "$body" -w '%{http_code}' "$HEALTH_URL") || code=000
echo "[$i] $HEALTH_URL -> $code"
[ "$code" = 200 ] && { echo "$HEALTH_URL is healthy"; exit 0; }
[ "$i" = "$HEALTH_ATTEMPTS" ] || sleep "$HEALTH_INTERVAL"
done
echo "::error::$HEALTH_URL did not answer 200${HEALTH_MEANS:+: $HEALTH_MEANS}"
head -c 600 "$body" 2>/dev/null; echo
exit 1
71 changes: 71 additions & 0 deletions actions/setup/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
name: Node, pnpm and the dependencies
description: >-
The toolchain the checkout pins (.node-version, packageManager) and `pnpm install --frozen-lockfile`, with the pnpm
store where the runner can keep it. Run it after actions/checkout.

inputs:
node-version-file:
description: The file that pins Node.
default: .node-version
install-args:
description: Extra arguments for `pnpm install --frozen-lockfile`, e.g. `--ignore-scripts` in a job that holds a deploy token.
default: ''

runs:
using: composite
steps:
- uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
with:
run_install: false

# About the disk, not the provider. pnpm hard-links node_modules out of its store, and a hard link cannot cross
# filesystems. A runner whose workspace sits on its own volume keeps one live store beside it, and no cache is
# restored or saved: a cache archive of a store other jobs are writing is torn. A runner whose workspace is on the
# root filesystem (a hosted VM) has no such store: it gets one inside the workspace, restored by setup-node's cache.
- name: Where the pnpm store lives
id: store
shell: bash
run: |
set -euo pipefail
# POSIX `df -P`: one line a filesystem, the mount point last. GNU's `--output=target` stops a macOS runner here.
# A mount point with a space in it is read short, finds no store, and falls to the last branch.
mount_point=$(df -P "$GITHUB_WORKSPACE" | tail -n 1 | awk '{print $NF}')
store="$mount_point/pnpm-store"
if [ "$mount_point" = "/" ]; then
store="$GITHUB_WORKSPACE/.pnpm-store"
echo "cache=true" >> "$GITHUB_OUTPUT"
echo "npm_config_store_dir=$store" >> "$GITHUB_ENV"
echo "pnpm store -> $store (in the workspace, restored from the Actions cache)"
elif [ -d "$store" ] && [ -w "$store" ]; then
echo "cache=false" >> "$GITHUB_OUTPUT"
echo "npm_config_store_dir=$store" >> "$GITHUB_ENV"
echo "pnpm store -> $store (kept on this runner, same filesystem as $GITHUB_WORKSPACE)"
else
echo "cache=false" >> "$GITHUB_OUTPUT"
echo "no writable store beside the workspace; pnpm's default store, no cache (installs copy instead of linking)"
fi

- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
if: steps.store.outputs.cache != 'true'
with:
node-version-file: ${{ inputs.node-version-file }}
package-manager-cache: false

- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
if: steps.store.outputs.cache == 'true'
with:
node-version-file: ${{ inputs.node-version-file }}
cache: pnpm
cache-dependency-path: |
pnpm-lock.yaml
package.json

- name: Install dependencies
shell: bash
env:
INSTALL_ARGS: ${{ inputs.install-args }}
run: |
set -euo pipefail
# Word-split on purpose: the input is a list of flags.
# shellcheck disable=SC2086
pnpm install --frozen-lockfile $INSTALL_ARGS
39 changes: 39 additions & 0 deletions actions/verify/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
name: Verify
description: >-
Run the checks the repository's gate file (Config/remote-gate.json) names: on a pull request the ones its diff
selects, on any other event the whole list. They run side by side in this one job and each prints one timed line.
Run it after actions/checkout (with the base commit present: fetch-depth 2 or more on a pull request) and after the
dependencies are installed.

inputs:
scope:
description: "`changed` runs what the diff from `base` selects; `all` runs the gate file's `default` list."
default: ${{ github.event_name == 'pull_request' && 'changed' || 'all' }}
alone:
description: Names of checks that run one at a time after the others, space separated, in that order (a build, a second typecheck).
default: ''
config:
description: The gate file, relative to the workspace.
default: Config/remote-gate.json
base:
description: The commit a pull request is compared with. HEAD^1 is the base branch on the merge commit a pull request checks out.
default: HEAD^1

runs:
using: composite
steps:
- name: Plan and run the checks
shell: bash
env:
VERIFY_SCOPE: ${{ inputs.scope }}
VERIFY_ALONE: ${{ inputs.alone }}
VERIFY_CONFIG: ${{ inputs.config }}
VERIFY_BASE: ${{ inputs.base }}
run: |
set -euo pipefail
case "$VERIFY_SCOPE" in
changed) python3 "$GITHUB_ACTION_PATH/verify.py" plan ;;
all) python3 "$GITHUB_ACTION_PATH/verify.py" plan --all ;;
*) echo "::error::scope must be changed or all, not '$VERIFY_SCOPE'"; exit 1 ;;
esac
python3 "$GITHUB_ACTION_PATH/verify.py" run
Loading
Loading