@futurelastic/colab-handbook 1.21.0-rc.1 → 1.21.0-rc.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/templates/README.md +25 -17
- package/templates/ci-call.yml +3 -2
- package/templates/ci-laravel.yml +128 -682
- package/templates/ci-node.yml +88 -676
- package/templates/ci-python.yml +104 -644
- package/tools/colab +52 -9
- package/tools/lib/blocked-by.js +3 -1
- package/tools/lib/gate-drift.js +3 -1
- package/tools/lib/stamp.js +15 -9
- package/tools/lib/template-roundtrip.js +7 -4
- package/tools/lib/template-trunk.js +23 -1
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -4,8 +4,9 @@ Starting points you **copy into your own repo**. That is the entire model.
|
|
|
4
4
|
|
|
5
5
|
> **These are NOT called remotely — with two exceptions.** `instruction-files.yml` is a caller:
|
|
6
6
|
> its one job `uses:` this handbook's reusable `.github/workflows/instruction-files.yml` (#588,
|
|
7
|
-
> kept for compatibility — see *Where each file lives* below).
|
|
8
|
-
>
|
|
7
|
+
> kept for compatibility — see *Where each file lives* below). The light CI templates are the other:
|
|
8
|
+
> `ci-node.yml`, `ci-python.yml`, `ci-laravel.yml` (since #724) and the generic `ci-call.yml` call the
|
|
9
|
+
> reusable light lane `.github/workflows/ci-light.yml`, pinned to a release tag (#721 — see
|
|
9
10
|
> *The reusable light lane* below). Every other file here is copied, not called. (`dist-refs.yml` is a
|
|
10
11
|
> `workflow_call` workflow, but its caller is your own release workflow, in the same repo, via
|
|
11
12
|
> `uses: ./.github/workflows/dist-refs.yml` — the file still lives, in full, where it runs.) An earlier version of this
|
|
@@ -103,11 +104,11 @@ check that reads one of these files is that tool's behaviour, documented with th
|
|
|
103
104
|
|
|
104
105
|
| File | Copy to | For | Notes |
|
|
105
106
|
|---|---|---|---|
|
|
106
|
-
| `ci-call.yml` | `.github/workflows/ci.yml` |
|
|
107
|
-
| `ci-node.yml` | `.github/workflows/ci.yml` | Pure Node repos: Vite SPA, node libs, Astro static, **Capacitor apps** |
|
|
108
|
-
| `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node.
|
|
109
|
-
| `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push.
|
|
110
|
-
| `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries |
|
|
107
|
+
| `ci-call.yml` | `.github/workflows/ci.yml` | The generic caller: a hybrid repo, or a stack with no `ci-<stack>.yml` of its own (#721) | **A caller, not a copy:** triggers, concurrency and one `uses:` of the handbook's reusable `.github/workflows/ci-light.yml` — the dedupe gate, the secret scan, a `quick` and a `full` job, job-class `runs-on`. `colab template ci-call` writes this repo's trunk refs and pins the call to the release it stamps. Your commands go in `with:` (`toolchain`, `install`, `quick`, `full`); your own jobs sit beside the call. A copied gate is reported as drift. |
|
|
108
|
+
| `ci-node.yml` | `.github/workflows/ci.yml` | Pure Node repos: Vite SPA, node libs, Astro static, **Capacitor apps** | A **caller** of `ci-light.yml` (#724), its `with:` filled in for Node: typecheck/lint in `quick`, `npm test` and the build in `full`, each only if `package.json` declares it. The call resolves Node from `project.yml` → `.nvmrc`/`engines` → **fails**. Never a default. Opt-in `Migration round-trip` job beside the call — `--roundtrip` writes it live, see *Migration round-trip* below. |
|
|
109
|
+
| `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | A **caller** of `ci-light.yml` (#724). Same resolution for **both** PHP and Node. Its `full` script carries the test tier (`RUN_TESTS`), the sqlite bootstrap + explicit wayfinder step and the Vite build; beside the call, a `migrations` job that round-trips the schema (migrate → rollback → seed → migrate, schema compared) on the test engine **and** the deploy engine (a MariaDB/MySQL service container at production's version). Its data-dependent checks need `ROUNDTRIP_SEEDER` — see *Migration round-trip* below. |
|
|
110
|
+
| `ci-node-heavy.yml`, `ci-python-heavy.yml`, `ci-laravel-heavy.yml` | `.github/workflows/ci-heavy.yml` | The heavy lane beside the matching `ci-<stack>.yml` (above) | `schedule` + `workflow_dispatch` + `workflow_call`, never a push. **Still a copy** (#724 kept it one: it runs nightly and on candidates, never per merge, so it is not what drifted, and its plan gate is per-repo). Its toolchain resolution follows the same precedence as the reusable light lane's, and the `secrets` job's gitleaks install and `GITLEAKS_VERSION` follow its `gitleaks` job — keep them in step. `TRUNK` is an edit point. |
|
|
111
|
+
| `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | A **caller** of `ci-light.yml` (#724): byte-compile, ruff and mypy in `quick`, pytest in `full`, each only if installed. The call resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: `toolchain: python,node` in the same call — see the template header. Opt-in `Migration round-trip` job, as in `ci-node.yml`. |
|
|
111
112
|
| `release-tag.yml` | `.github/workflows/release.yml` | Any repo cutting `v*.*.*` releases | Triggers on tag push. Publishes a grouped GitHub Release — a `-rc.N` tag as a pre-release, every summary since the previous *final* tag. No toolchain, no deploy; its header shows the `!v*.*.*-*` exclusion a deploy trigger needs. |
|
|
112
113
|
| `release-auto.yml` | `.github/workflows/release-auto.yml` | A repo whose release tags land on `main` (`trunk: main`, `deploy: tag` or `none`) and whose §6 release route cuts candidates | Runs `colab release cut --auto` after CI goes green on main — at the sha that CI run tested (`--sha`, #622), even once main has moved on — and `colab release finalize --auto` daily — plus an hourly run that re-tries only a refused cut, once the fetched CLI has moved within `RETRY_WINDOW_MINUTES` or a run at main's head was cancelled (#547) — from a handbook ref (`HANDBOOK_REF` — the `stable` channel by default, `next` for the fast channel, or an exact tag to freeze; #445) — the handbook's own copy runs its checkout's CLI instead, since it ships the CLI it releases with (#428). **Publishes the Release in the same run** — a tag pushed with `GITHUB_TOKEN` triggers no other workflow, so `release-tag.yml` would never fire for it. A refusal is a warning, not a red run. Reads and creates tags, and fast-forwards the release channels `next` / `stable` (branches naming the newest candidate / final, #445); never pushes a commit. The audit recognises any workflow running `release cut/finalize --auto` and warns when the route leaves candidates off, when it tags without publishing while a tag-push workflow waits, or when it commits. |
|
|
113
114
|
| `forgejo-release-auto.yml` | `.forgejo/workflows/release-auto.yml` | A repo hosted on **Forgejo** (or Gitea) whose §6 release route cuts candidates, with the forge named in the machine config's `forges` (#678) | The Forgejo dialect of `release-auto.yml` (#681). It has no `workflow_run`: the job you append to your CI (in its header) dispatches it when CI ends green, with `source=ci-completed` and the sha it tested. It waits for CI at that sha (`colab ci-wait`), then runs `colab release cut --auto --sha`, which tags the candidate and publishes its pre-release through the forge's API. No `permissions:` blocks, full-URL `uses:`, the runner label from the `RELEASE_RUNNER` variable, verdicts printed to the log (Forgejo drops the step summary), no `jq`. A refusal stays green. No verdict is a red run. **No finalize step**: on a forge a final is a human's `release finalize` under the human bar, which also publishes the final's release, so no tag-push workflow is needed. Keep its `name:` equal to the file's base name, because the CLI drops its own statuses by that name. |
|
|
@@ -183,26 +184,33 @@ run cannot: secrets only trunk gets, `github.ref`-conditional steps, unpinned ru
|
|
|
183
184
|
The guard above drifted copy by copy: measured across adopters (2026-11-09 → 11-11), missing in six
|
|
184
185
|
repositories and present but never skipping in three, and #717's fix reached a copy only through a manual
|
|
185
186
|
sync. `.github/workflows/ci-light.yml` carries the same guard, the same secret scan and the descriptor check
|
|
186
|
-
once, for every caller; `ci-
|
|
187
|
+
once, for every caller; `ci-node.yml`, `ci-python.yml` and `ci-laravel.yml` are its callers since #724, and
|
|
188
|
+
`ci-call.yml` is the generic one. What changes for you:
|
|
187
189
|
|
|
188
190
|
- **Only the caller is yours**: the triggers and `concurrency` (a called workflow cannot own either), the
|
|
189
191
|
`with:` block, and your own jobs beside the call. A job behind the gate reads `needs: ci` +
|
|
190
|
-
`if: ${{ !cancelled() && needs.ci.outputs.tested != 'true' }}
|
|
191
|
-
in `trunk-only-jobs` (#717).
|
|
192
|
-
- **Pinned to a release tag, never `main`.** `colab template ci
|
|
193
|
-
with; `colab update` moves a pristine copy's stamp and pin together
|
|
192
|
+
`if: ${{ !cancelled() && needs.ci.result == 'success' && needs.ci.outputs.tested != 'true' }}` (the
|
|
193
|
+
result term keeps it off a red call); a trunk-only job outside it is named in `trunk-only-jobs` (#717).
|
|
194
|
+
- **Pinned to a release tag, never `main`.** `colab template ci-<stack>` writes the version it stamps the
|
|
195
|
+
copy with; `colab update` moves a pristine copy's stamp and pin together — including a pristine full copy
|
|
196
|
+
from before #724, which it moves onto the caller. **Until a final release carries `ci-light.yml`** (the
|
|
197
|
+
stamp is always the latest final, never a candidate, #334), `colab template ci-<stack>` and `colab update`
|
|
198
|
+
write that release's *own* template — a full copy that runs today — never a caller pinned at a release
|
|
199
|
+
that cannot run it (#724).
|
|
194
200
|
- **The quick/full split is two jobs**: `quick` (descriptor check, lint, types, unit — the `quick` class)
|
|
195
201
|
and `full` (the light suite, the build — the `full` class); both run on every push the gate does not skip,
|
|
196
202
|
and both take the `trunk` class on a trunk ref under `runs-on: classes`.
|
|
197
|
-
- The
|
|
198
|
-
|
|
199
|
-
|
|
203
|
+
- **The package caches moved too**: npm, pip and Composer, each on only on a GitHub-hosted runner and with
|
|
204
|
+
its lockfile present (#571), now in the call. Laravel's PHP extensions are the `php-extensions` input.
|
|
205
|
+
- A workflow still carrying its own copy of the gate is reported as drift — a suggestion until a handbook
|
|
206
|
+
release tag carries `ci-light.yml`, a warning from then on.
|
|
200
207
|
|
|
201
208
|
### Migration round-trip — have it from the first copy
|
|
202
209
|
|
|
203
210
|
`migration-grant: reviewer` grants only where a `Migration round-trip…` job passed at the
|
|
204
211
|
shipped head (condition R, [CONVENTIONS §5](../CONVENTIONS.md#migration-exemption--a-narrow-door-through-no-new-migrations-opened-by-a-role-98-402)).
|
|
205
|
-
`ci-laravel.yml` always carries it
|
|
212
|
+
`ci-laravel.yml` always carries it, as a job beside the call (`needs: ci`, behind the gate). `ci-node.yml`
|
|
213
|
+
and `ci-python.yml` carry it as an opt-in
|
|
206
214
|
block, and **the time to opt in is the copy** (#625):
|
|
207
215
|
|
|
208
216
|
```sh
|
|
@@ -214,7 +222,7 @@ colab template ci-python --dest .github/workflows/ci.yml --roundtrip --roundtrip
|
|
|
214
222
|
that can rewrite the job grading it never passes R — so that one branch, and its migration,
|
|
215
223
|
ships on a human grant. In the commit that creates the workflows, there is no such branch.
|
|
216
224
|
- **No migrations yet?** Leave out `--roundtrip-apply`. The job is written but **skipped**
|
|
217
|
-
until `ROUNDTRIP_APPLY` (
|
|
225
|
+
until `ROUNDTRIP_APPLY` (the `roundtrip-config` job's `env`, beside the call — a job-level `if:` cannot read `env`, so that small job hands it on) is set: a skipped leg never passes
|
|
218
226
|
R, so migrations ship on a human grant, and CI stays green — a fresh repo is not held red.
|
|
219
227
|
The build job prints a warning saying so. The cost while skipped: trunk does not reuse a
|
|
220
228
|
branch's identical-tree run (#511). A green no-op job would pass R without testing
|
package/templates/ci-call.yml
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# CI (light lane) — CALLER of the handbook's reusable workflow (#721). Copy to .github/workflows/ci.yml
|
|
2
2
|
# with `colab template ci-call --dest .github/workflows/ci.yml`: it writes this repo's trunk refs and pins the call to the handbook
|
|
3
|
-
# release it stamps the copy with.
|
|
3
|
+
# release it stamps the copy with. Like templates/ci-<stack>.yml (callers too since #724, each with one
|
|
4
|
+
# stack's `with:` filled in — this one is the generic caller, for a hybrid), nothing below the `uses:` line is
|
|
4
5
|
# yours to maintain — the dedupe gate, the secret scan, the quick/full split and the job-class
|
|
5
6
|
# `runs-on` live once, in .github/workflows/ci-light.yml of the handbook, and a release moves them.
|
|
6
7
|
#
|
|
@@ -69,5 +70,5 @@ jobs:
|
|
|
69
70
|
|
|
70
71
|
# Your own jobs go here, beside the call. Behind the gate (they skip when the tree already passed):
|
|
71
72
|
# needs: ci
|
|
72
|
-
# if: ${{ !cancelled() && needs.ci.outputs.tested != 'true' }}
|
|
73
|
+
# if: ${{ !cancelled() && needs.ci.result == 'success' && needs.ci.outputs.tested != 'true' }}
|
|
73
74
|
# Trunk-only and ungated: no `if:` on the guard, and list the job's name in `trunk-only-jobs` above.
|