@futurelastic/colab-handbook 1.12.0-rc.8 → 1.12.0
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/README.md +7 -4
- package/README.vi.md +4 -2
- package/audit/audit.mjs +4 -2
- package/package.json +1 -1
- package/templates/README.md +21 -2
- package/templates/ci-laravel.yml +82 -0
- package/templates/ci-node.yml +79 -0
- package/templates/ci-python.yml +79 -0
- package/templates/pre-push-guard +21 -1
- package/templates/release-auto.yml +31 -6
- package/tools/colab +149 -22
- package/tools/lib/conflict-markers.js +47 -0
- package/tools/lib/hermetic.js +72 -6
- package/tools/lib/install-check.js +20 -1
- package/tools/lib/notify-endpoint.js +170 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-finalize.js +51 -11
- package/tools/lib/ship-batch.js +11 -1
- package/tools/lib/stamp.js +38 -1
package/README.md
CHANGED
|
@@ -187,6 +187,7 @@ you want.
|
|
|
187
187
|
| `--hooks` | Point this clone's git at `.githooks/`, whose `pre-commit` runs every check in `pre-commit.d/` — a gitleaks secret scan, and an identity scan that needs a vocabulary you supply by path and keep outside every repo (see [`templates/README.md`](templates/README.md)). `core.hooksPath` lives in `.git/config`, so it is per-clone, per-machine, and never travels with the repo. |
|
|
188
188
|
| `--fleet` | Seed `~/.colab/repos.txt` from `audit/repos.txt`, only if it is absent. The seed is format notes and commented placeholders — it registers **nothing**; `colab register <path>` (step 3) is what fills it. That list stays machine-local on purpose: it names your private repos, and this repo is public. |
|
|
189
189
|
| `--all` | `--tools --hooks --fleet`. |
|
|
190
|
+
| `--notify-url <url>` | Seed `notifyUrl` in `~/.colab/config.json` with a local observer's events URL, only when the key is absent — an existing value is never overwritten. Without the flag, `--tools` seeds it from `~/.colab/notify-endpoint` when a local observer declared its URL there, and otherwise prints that `notifyUrl` is unset and which events that drops. See [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
|
|
190
191
|
| `--dry` | Print what would happen, change nothing. Combines with all of the above. |
|
|
191
192
|
| `--check` | **Read-only** health report on what an earlier install left behind — see *Checking an install* below. Takes no other flag; exit 1 on any ✗ row. |
|
|
192
193
|
|
|
@@ -216,14 +217,15 @@ window between a CLI commit and the next tag, and the advertised remedy copies
|
|
|
216
217
|
*from* that same working tree — so on a machine developing the handbook it
|
|
217
218
|
advised services to adopt untagged code.) It never rewrites the copy, not even
|
|
218
219
|
with `--apply`: that is the toolchain your running services are executing.
|
|
219
|
-
`colab --version` says which of the two you are talking to
|
|
220
|
+
`colab --version` says which of the two you are talking to (or `npm package` for an
|
|
221
|
+
`npx`/`npm i` install), and prints that install's version. The frozen copy carries
|
|
220
222
|
`tools/` only, so `colab template` refuses there — run it from the working tree.
|
|
221
223
|
|
|
222
224
|
**3. Verify, and register your repos.**
|
|
223
225
|
|
|
224
226
|
```sh
|
|
225
227
|
colab --help # not found? fix your PATH — step 2 prints the exact line
|
|
226
|
-
colab --version # which colab is this
|
|
228
|
+
colab --version # which colab is this — working tree, frozen copy, or npm package — and its version
|
|
227
229
|
colab register /path/to/repo # once per repo — writes repos.txt AND config.json, so they agree
|
|
228
230
|
node audit/audit.mjs # a conformance report across the whole fleet
|
|
229
231
|
colab update # stamped copies that fell behind — the frozen CLI included
|
|
@@ -245,8 +247,9 @@ A frozen copy never breaks — it gets **old**, and an old complete copy answers
|
|
|
245
247
|
normally for every command it knows until something asks for one added after it
|
|
246
248
|
was frozen. `--check` is the report nothing else gives: whether the frozen copy is
|
|
247
249
|
behind the latest release, **which commands it does not dispatch**, whether the
|
|
248
|
-
state file exists, whether anything is registered,
|
|
249
|
-
hooklets can actually run (gitleaks, and the identity vocabulary)
|
|
250
|
+
state file exists, whether anything is registered, whether both pre-commit
|
|
251
|
+
hooklets can actually run (gitleaks, and the identity vocabulary), and whether
|
|
252
|
+
`notifyUrl` is unset while a local observer declared an endpoint. ✗ means
|
|
250
253
|
something installed here is stale or unusable; ⚠ means something was never set
|
|
251
254
|
up, which may be deliberate. It never refreshes anything — re-freezing stays your
|
|
252
255
|
call: `./install.sh --tools`.
|
package/README.vi.md
CHANGED
|
@@ -185,6 +185,7 @@ nếu bạn thật sự chỉ cần bấy nhiêu.
|
|
|
185
185
|
| `--hooks` | Trỏ git của clone này vào `.githooks/`, ở đó `pre-commit` chạy lần lượt mọi check trong `pre-commit.d/` — quét secret bằng gitleaks, và quét danh tính (identity) vốn cần một danh sách từ khoá do bạn cấp bằng đường dẫn và giữ NGOÀI mọi repo (xem [`templates/README.md`](templates/README.md)). `core.hooksPath` nằm trong `.git/config` nên là cấu hình per-clone, per-máy, không đi theo repo. |
|
|
186
186
|
| `--fleet` | Tạo `~/.colab/repos.txt` từ `audit/repos.txt`, chỉ khi file chưa tồn tại. Danh sách đó cố tình nằm ngoài repo: nó ghi tên các repo private của bạn, còn repo này thì public. |
|
|
187
187
|
| `--all` | `--tools --hooks --fleet`. |
|
|
188
|
+
| `--notify-url <url>` | Ghi `notifyUrl` vào `~/.colab/config.json` bằng URL nhận event của một observer chạy trên máy, chỉ khi khoá đó chưa có — giá trị đang có không bao giờ bị ghi đè. Không truyền flag thì `--tools` lấy URL từ `~/.colab/notify-endpoint` nếu observer trên máy đã khai ở đó; không có thì in rõ `notifyUrl` đang trống và sẽ mất những event nào. Xem [`tools/README.md`](tools/README.md#notifyurl--optional-event-push-off-by-default). |
|
|
188
189
|
| `--dry` | In ra sẽ làm gì, không thay đổi gì. Ghép được với mọi flag trên. |
|
|
189
190
|
|
|
190
191
|
**Service luôn-bật phải gọi `~/.colab/bin/colab`.** Bản CLI symlink chạy theo
|
|
@@ -208,13 +209,14 @@ mọi máy bị đánh dấu cũ suốt quãng từ lúc commit CLI tới tag k
|
|
|
208
209
|
phục được quảng cáo lại copy *từ* chính cây làm việc đó — nên trên máy đang phát
|
|
209
210
|
triển handbook, nó khuyên các service nạp code chưa phát hành.) Nó không bao giờ
|
|
210
211
|
ghi đè bản copy, kể cả với `--apply`: đó là bộ công cụ mà các service đang chạy
|
|
211
|
-
của bạn đang thực thi. `colab --version` cho biết bạn đang nói chuyện với bản nào
|
|
212
|
+
của bạn đang thực thi. `colab --version` cho biết bạn đang nói chuyện với bản nào (hoặc `npm package` khi
|
|
213
|
+
cài qua `npx`/`npm i`), kèm phiên bản của chính bản đó.
|
|
212
214
|
|
|
213
215
|
**3. Kiểm lại, rồi chỉ cho audit biết phải soi repo nào.**
|
|
214
216
|
|
|
215
217
|
```sh
|
|
216
218
|
colab --help # không thấy lệnh? sửa PATH — bước 2 in sẵn dòng cần thêm
|
|
217
|
-
colab --version # colab nào đây
|
|
219
|
+
colab --version # colab nào đây — working tree, bản đóng băng hay npm package — và phiên bản của nó
|
|
218
220
|
$EDITOR ~/.colab/repos.txt # thay các dòng ví dụ bằng repo của bạn
|
|
219
221
|
node audit/audit.mjs # báo cáo conformance cho toàn bộ fleet
|
|
220
222
|
colab update # các bản copy có đóng dấu đã tụt lại — kể cả CLI đóng băng
|
package/audit/audit.mjs
CHANGED
|
@@ -1270,12 +1270,14 @@ function auditRepo(target, ctx) {
|
|
|
1270
1270
|
// ---- ship-batch (#373) ------------------------------------------------------
|
|
1271
1271
|
// Batch landing's opt-in: an integer 1–3 (tools/lib/ship-batch.js parseShipBatch — the one reading
|
|
1272
1272
|
// `colab ship --batch` uses, so the two cannot disagree). A malformed value makes ship fail closed
|
|
1273
|
-
// to serial, which is safe but silent, so it fails here
|
|
1273
|
+
// to serial, which is safe but silent, so it fails here — and, since this audit is run by hand, in
|
|
1274
|
+
// the CI templates' descriptor check too (#416, held to this same parser by
|
|
1275
|
+
// tools/lib/ci-template-descriptor-check.test.js). Two further shapes are inert rather than
|
|
1274
1276
|
// wrong, so they warn: no workflow fires on a `ship-batch/**` push (the combined run can never
|
|
1275
1277
|
// arrive), and no `autonomy: auto-trunk` (a batch lands in one unattended push, which needs it).
|
|
1276
1278
|
if ("ship-batch" in (cfg || {}) && cfg["ship-batch"] !== null) {
|
|
1277
1279
|
const sbCfg = shipBatch.parseShipBatch(cfg);
|
|
1278
|
-
if (!sbCfg.valid) fail(sbCfg.reason);
|
|
1280
|
+
if (!sbCfg.valid) fail(`${sbCfg.reason} — the cap is deliberate, see project.schema.md, ship-batch`);
|
|
1279
1281
|
else if (sbCfg.n > 1) {
|
|
1280
1282
|
const firing = workflowsFiringOnBranchPush({ readFile: (p) => src.readFile(p), workflows, branch: shipBatch.PROBE_REF });
|
|
1281
1283
|
if (!firing.length) warn(`ship-batch: ${sbCfg.n} but no workflow in .github/workflows fires on a push to ship-batch/** — colab ship --batch will always fall back to serial; add 'ship-batch/**' to a CI workflow's push: branches:`);
|
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -20,7 +20,7 @@ Starting points you **copy into your own repo**. That is the entire model.
|
|
|
20
20
|
| `ci-laravel.yml` | `.github/workflows/ci.yml` | Laravel + Inertia + Vite fullstack (with route/type codegen) | Same resolution for **both** PHP and Node. Includes the sqlite bootstrap + explicit wayfinder step, and 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. |
|
|
21
21
|
| `ci-python.yml` | `.github/workflows/ci.yml` | Python: FastAPI/Flask services, CLIs, libraries | Resolves Python from `project.yml` → `.python-version`/`requires-python` → **fails**. `requirements.txt` does not count. **Hybrid** Python+Node repo: copy this, then paste `ci-node.yml`'s `build:` job alongside — see the template header. |
|
|
22
22
|
| `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. |
|
|
23
|
-
| `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 and `colab release finalize --auto` daily, from a
|
|
23
|
+
| `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 and `colab release finalize --auto` daily, 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. |
|
|
24
24
|
| `dist-refs.yml` | `.github/workflows/dist-refs.yml` | A **private** repo shipping a **compiled** tool, installed as `npx github:<org>/<repo>#vX.Y.Z` ([CONVENTIONS §6, *Distribution*](../CONVENTIONS.md#distribution--one-install-surface-npx-442)) | `workflow_call`, called from the same run that cut the release tag (a tag pushed with `GITHUB_TOKEN` triggers nothing else). Takes one build artifact per `<os>-<arch>` and pushes each as an orphan commit at `refs/tags/dist/vX.Y.Z/<os>-<arch>` with a `SHA256SUMS`. Refuses a public or unreadable repository (a public compiled tool ships npm platform packages instead), a version that is not an existing tag, and a missing platform — before pushing any. Never moves a dist ref that exists. |
|
|
25
25
|
| `npx-launcher.mjs` | anywhere in-repo (e.g. `bin/launch.mjs`), named by the root `package.json`'s `bin` | Pairs with `dist-refs.yml` | Node ≥ 18, zero dependencies, needs `git`. Reads the `#vX.Y.Z` npx installed, fetches that one dist ref with the same URL and credentials npx cloned with, verifies `SHA256SUMS`, installs to a stable per-user path (`$XDG_DATA_HOME`/`%LOCALAPPDATA%`), and execs it; `--print-path` prints that path for a service's `init`. `*.mjs`, so `colab template npx-launcher.mjs --dest <path>` copies it stamped, `--dest` required. One edit point: `BIN` (defaults to the package name without its scope). |
|
|
26
26
|
| `deploy-xserver.yml` | `.github/workflows/deploy-xserver.yml` | PHP-framework + Vite apps shipped to **shared hosting over SSH** (no root, no Docker): build on a runner, rsync, migrate on the server | Derived from three independently-written copies. Resolves Node the same way the CI templates do — all three hardcoded it, and one shipped on a different major than its CI built on. Migrates **production**; keeps a **mandatory** smoke test. Does **not** change your tier. |
|
|
@@ -31,6 +31,25 @@ Starting points you **copy into your own repo**. That is the entire model.
|
|
|
31
31
|
| `docs-lint.yml` | `.github/workflows/docs-lint.yml` | Every repo that copied `docs-lint.mjs` | Advisory job — `continue-on-error: true` on the lint step, so a finding never blocks a merge until a repo deliberately removes that line. Requires `docs-lint.mjs` to already be in the repo; does not vendor it. |
|
|
32
32
|
| `branch-name.yml` | `.github/workflows/branch-name.yml` | Opt-in — any repo that wants §4's branch shape checked on every PR | One step, no dependencies: the PR's head branch against CONVENTIONS.md §4's regex, both shapes (`<type>/<slug>-<N>` and the `<login>/<machine>/` prefixed one) passing as shipped. Once the repo declares `branchPrefix: machine`, delete the `?` after the regex's first group to require the prefix. The head ref reaches the script through `env:`, never interpolated — on a public repo it is attacker-chosen. |
|
|
33
33
|
|
|
34
|
+
### The `dedupe` job — why a claimed branch's first run skips the suite (#418)
|
|
35
|
+
|
|
36
|
+
All three CI templates open with a `dedupe` job. It runs only on the push that **creates** a
|
|
37
|
+
ref, which is what a session claim does: it pushes the new branch at trunk's head. It checks
|
|
38
|
+
nothing out, needs `permissions: actions: read`, and asks whether this same workflow already
|
|
39
|
+
has a green, non-pull-request run at this exact sha. If one exists, every other job is
|
|
40
|
+
skipped and the run still concludes `success`. If not, or if the check cannot run, the suite
|
|
41
|
+
runs as before. Every later push skips the guard, so real commits always get the full suite.
|
|
42
|
+
Two things to keep in a copy:
|
|
43
|
+
|
|
44
|
+
- **The guard calls `gh`.** GitHub-hosted images have it. On a self-hosted image without
|
|
45
|
+
`gh`, the guard prints a notice and the suite runs, so nothing breaks, but nothing is saved
|
|
46
|
+
either.
|
|
47
|
+
- **Every other job needs `!cancelled()` in its `if:`.** Without it, a job inherits the
|
|
48
|
+
implicit `success()`, which reads every ancestor, `dedupe` included. A job that only needs
|
|
49
|
+
`dedupe` indirectly would then be skipped on every ordinary push. That is why the Laravel
|
|
50
|
+
`migrations` job checks `needs.build.result == 'success'` explicitly. Add the same pair of
|
|
51
|
+
conditions to any job you add.
|
|
52
|
+
|
|
34
53
|
### Migration round-trip — what the Laravel job proves, and what it cannot
|
|
35
54
|
|
|
36
55
|
`ci-laravel.yml`'s `migrations` job runs every migration **twice per engine**: once from
|
|
@@ -69,7 +88,7 @@ a workflow.
|
|
|
69
88
|
|
|
70
89
|
| File | Copy to | For | Notes |
|
|
71
90
|
|---|---|---|---|
|
|
72
|
-
| `pre-push-guard` | `<hooks>/pre-push` | Every repo with a protected trunk | Refuses a raw push to trunk, a declared integration line, or `main` on a repo that promotes. Reads `project.yml`; missing descriptor → allows, with a warning. |
|
|
91
|
+
| `pre-push-guard` | `<hooks>/pre-push` | Every repo with a protected trunk | Refuses a raw push to trunk, a declared integration line, or `main` on a repo that promotes, and the release channels `next` / `stable`, which only `colab release cut` / `finalize` move (#445). Reads `project.yml`; missing descriptor → allows, with a warning. |
|
|
73
92
|
| `pre-commit-dispatch` | `<hooks>/pre-commit` | Any repo that needs **more than one** pre-commit check | Runs every hooklet in `pre-commit.d/`, fails if any failed, and **refuses when there is nothing to run**. Read its header before installing — it replaces a hook you already have, and step 2 of its instructions is where your existing check survives. |
|
|
74
93
|
| `pre-commit-identity` | `<hooks>/pre-commit.d/20-identity` | Any repo that could publish an identity — every public one, and any private one that may ever be opened | Scans staged content against a vocabulary the operator supplies **by path**. Also installs as `commit-msg`. |
|
|
75
94
|
| `identity-vocabulary.example` | *outside every repo* — e.g. `~/.colab/identity-vocabulary` | The above | Invented entries. **A real one is never committed anywhere**, which is the whole reason the scanner takes a path instead of shipping a list. |
|
package/templates/ci-laravel.yml
CHANGED
|
@@ -104,8 +104,59 @@ env:
|
|
|
104
104
|
# jobs from different runs interleave, and trunk can wait behind branch runs.
|
|
105
105
|
# Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
|
|
106
106
|
jobs:
|
|
107
|
+
# Already tested at this sha? (#418) — the claim push.
|
|
108
|
+
# A session's claim pushes its branch at the moment it is cut (CONVENTIONS.md §5, the
|
|
109
|
+
# claim record), so the branch's first push sits on a sha trunk has usually already
|
|
110
|
+
# run. Without this job that push re-runs the whole suite on a tested commit (~19% of
|
|
111
|
+
# all runs, measured across five adopting repos). This job runs ONLY on a ref's first
|
|
112
|
+
# push (`github.event.created`), checks nothing out, and asks one question: does THIS
|
|
113
|
+
# workflow already have a completed, green, non-PR run at THIS exact sha? Yes → every
|
|
114
|
+
# other job is skipped and the run concludes `success` — a branch-CI `green` that is
|
|
115
|
+
# true, because the same workflow passed at the same sha. Anything else — trunk still
|
|
116
|
+
# running, red, never run, `gh` missing, the API failing — and the suite runs as
|
|
117
|
+
# before (fail-open: this job never fails the run). Every later push has
|
|
118
|
+
# `created == false`, so a real commit always gets the full suite, with no extra hop.
|
|
119
|
+
# Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
|
|
120
|
+
# skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
|
|
121
|
+
# §4, "Branch CI"). This job is the one that ends green.
|
|
122
|
+
dedupe:
|
|
123
|
+
name: Already tested at this sha?
|
|
124
|
+
if: github.event_name == 'push' && github.event.created
|
|
125
|
+
runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
|
|
126
|
+
permissions:
|
|
127
|
+
actions: read
|
|
128
|
+
outputs:
|
|
129
|
+
tested: ${{ steps.check.outputs.tested }}
|
|
130
|
+
steps:
|
|
131
|
+
- name: Look for a green run of this workflow at this sha
|
|
132
|
+
id: check
|
|
133
|
+
env:
|
|
134
|
+
GH_TOKEN: ${{ github.token }}
|
|
135
|
+
REPO: ${{ github.repository }}
|
|
136
|
+
RUN_ID: ${{ github.run_id }}
|
|
137
|
+
SHA: ${{ github.sha }}
|
|
138
|
+
run: |
|
|
139
|
+
tested=false
|
|
140
|
+
if ! command -v gh >/dev/null 2>&1; then
|
|
141
|
+
echo "::notice::gh is not installed on this runner — running the full suite (#418)."
|
|
142
|
+
elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
|
|
143
|
+
echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
|
|
144
|
+
elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
|
|
145
|
+
--jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
|
|
146
|
+
echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
|
|
147
|
+
elif [ "${N:-0}" -ge 1 ] 2>/dev/null; then
|
|
148
|
+
tested=true
|
|
149
|
+
echo "This workflow already passed at $SHA ($N green run(s)) — skipping the suite (#418)."
|
|
150
|
+
echo "Already tested: this workflow has a green run at \`$SHA\` — suite skipped (#418)." >> "$GITHUB_STEP_SUMMARY"
|
|
151
|
+
else
|
|
152
|
+
echo "No green run of this workflow at $SHA yet — running the full suite."
|
|
153
|
+
fi
|
|
154
|
+
echo "tested=$tested" >> "$GITHUB_OUTPUT"
|
|
155
|
+
|
|
107
156
|
gitleaks:
|
|
108
157
|
name: Secret scan (gitleaks)
|
|
158
|
+
needs: dedupe
|
|
159
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
109
160
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
110
161
|
steps:
|
|
111
162
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
@@ -145,6 +196,8 @@ jobs:
|
|
|
145
196
|
|
|
146
197
|
build:
|
|
147
198
|
name: Build (Laravel + Vite)
|
|
199
|
+
needs: dedupe
|
|
200
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
148
201
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
149
202
|
# Re-exported so the migrations job below resolves PHP exactly once, here.
|
|
150
203
|
outputs:
|
|
@@ -154,6 +207,31 @@ jobs:
|
|
|
154
207
|
with:
|
|
155
208
|
persist-credentials: false
|
|
156
209
|
|
|
210
|
+
# ---------------------------------------------------------------------------
|
|
211
|
+
# Descriptor check (#416). A value `colab ship` cannot use does not fail there —
|
|
212
|
+
# it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
|
|
213
|
+
# once turned every landing in a busy repo back to serial while this CI stayed
|
|
214
|
+
# green; only a ship dry run noticed. So the value fails HERE, where the person
|
|
215
|
+
# who changed project.yml is looking. Same rule as `colab ship` and the audit
|
|
216
|
+
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
217
|
+
# cap is 3: project.schema.md, `ship-batch`.
|
|
218
|
+
# ---------------------------------------------------------------------------
|
|
219
|
+
- name: Descriptor check (.github/project.yml)
|
|
220
|
+
working-directory: ${{ github.workspace }}
|
|
221
|
+
run: |
|
|
222
|
+
[ -f .github/project.yml ] || exit 0
|
|
223
|
+
line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
|
|
224
|
+
[ -n "$line" ] || exit 0
|
|
225
|
+
v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
|
|
226
|
+
-e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
|
|
227
|
+
-e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
|
|
228
|
+
case "$v" in
|
|
229
|
+
''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
|
|
230
|
+
*)
|
|
231
|
+
echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
|
|
232
|
+
exit 1 ;;
|
|
233
|
+
esac
|
|
234
|
+
|
|
157
235
|
# ---------------------------------------------------------------------------
|
|
158
236
|
# Toolchain resolution. Precedence, highest first:
|
|
159
237
|
# PHP : 1. .github/project.yml -> php: 2. composer.json -> require.php
|
|
@@ -351,6 +429,10 @@ jobs:
|
|
|
351
429
|
migrations:
|
|
352
430
|
name: Migration round-trip (${{ matrix.engine }})
|
|
353
431
|
needs: build
|
|
432
|
+
# Explicit result check, not the implicit success(): success() reads EVERY ancestor,
|
|
433
|
+
# including `dedupe`, which is skipped on every ordinary push — so the implicit
|
|
434
|
+
# form would skip this job on exactly the runs it exists for (#418).
|
|
435
|
+
if: ${{ !cancelled() && needs.build.result == 'success' }}
|
|
354
436
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
355
437
|
strategy:
|
|
356
438
|
fail-fast: false
|
package/templates/ci-node.yml
CHANGED
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
# `php artisan wayfinder:generate` and needs PHP on the runner. Use ci-laravel.yml.
|
|
14
14
|
#
|
|
15
15
|
# What it does:
|
|
16
|
+
# 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416).
|
|
16
17
|
# 1. Resolve the Node version from declared sources — never a hardcoded default.
|
|
17
18
|
# 2. Secret scan with gitleaks (pinned release binary, see note at the step).
|
|
18
19
|
# 3. Install dependencies with the package manager the lockfile implies.
|
|
@@ -68,8 +69,59 @@ env:
|
|
|
68
69
|
# jobs from different runs interleave, and trunk can wait behind branch runs.
|
|
69
70
|
# Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
|
|
70
71
|
jobs:
|
|
72
|
+
# Already tested at this sha? (#418) — the claim push.
|
|
73
|
+
# A session's claim pushes its branch at the moment it is cut (CONVENTIONS.md §5, the
|
|
74
|
+
# claim record), so the branch's first push sits on a sha trunk has usually already
|
|
75
|
+
# run. Without this job that push re-runs the whole suite on a tested commit (~19% of
|
|
76
|
+
# all runs, measured across five adopting repos). This job runs ONLY on a ref's first
|
|
77
|
+
# push (`github.event.created`), checks nothing out, and asks one question: does THIS
|
|
78
|
+
# workflow already have a completed, green, non-PR run at THIS exact sha? Yes → every
|
|
79
|
+
# other job is skipped and the run concludes `success` — a branch-CI `green` that is
|
|
80
|
+
# true, because the same workflow passed at the same sha. Anything else — trunk still
|
|
81
|
+
# running, red, never run, `gh` missing, the API failing — and the suite runs as
|
|
82
|
+
# before (fail-open: this job never fails the run). Every later push has
|
|
83
|
+
# `created == false`, so a real commit always gets the full suite, with no extra hop.
|
|
84
|
+
# Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
|
|
85
|
+
# skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
|
|
86
|
+
# §4, "Branch CI"). This job is the one that ends green.
|
|
87
|
+
dedupe:
|
|
88
|
+
name: Already tested at this sha?
|
|
89
|
+
if: github.event_name == 'push' && github.event.created
|
|
90
|
+
runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
|
|
91
|
+
permissions:
|
|
92
|
+
actions: read
|
|
93
|
+
outputs:
|
|
94
|
+
tested: ${{ steps.check.outputs.tested }}
|
|
95
|
+
steps:
|
|
96
|
+
- name: Look for a green run of this workflow at this sha
|
|
97
|
+
id: check
|
|
98
|
+
env:
|
|
99
|
+
GH_TOKEN: ${{ github.token }}
|
|
100
|
+
REPO: ${{ github.repository }}
|
|
101
|
+
RUN_ID: ${{ github.run_id }}
|
|
102
|
+
SHA: ${{ github.sha }}
|
|
103
|
+
run: |
|
|
104
|
+
tested=false
|
|
105
|
+
if ! command -v gh >/dev/null 2>&1; then
|
|
106
|
+
echo "::notice::gh is not installed on this runner — running the full suite (#418)."
|
|
107
|
+
elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
|
|
108
|
+
echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
|
|
109
|
+
elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
|
|
110
|
+
--jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
|
|
111
|
+
echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
|
|
112
|
+
elif [ "${N:-0}" -ge 1 ] 2>/dev/null; then
|
|
113
|
+
tested=true
|
|
114
|
+
echo "This workflow already passed at $SHA ($N green run(s)) — skipping the suite (#418)."
|
|
115
|
+
echo "Already tested: this workflow has a green run at \`$SHA\` — suite skipped (#418)." >> "$GITHUB_STEP_SUMMARY"
|
|
116
|
+
else
|
|
117
|
+
echo "No green run of this workflow at $SHA yet — running the full suite."
|
|
118
|
+
fi
|
|
119
|
+
echo "tested=$tested" >> "$GITHUB_OUTPUT"
|
|
120
|
+
|
|
71
121
|
gitleaks:
|
|
72
122
|
name: Secret scan (gitleaks)
|
|
123
|
+
needs: dedupe
|
|
124
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
73
125
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
74
126
|
steps:
|
|
75
127
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
@@ -114,6 +166,8 @@ jobs:
|
|
|
114
166
|
|
|
115
167
|
build:
|
|
116
168
|
name: Build
|
|
169
|
+
needs: dedupe
|
|
170
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
117
171
|
# A repo can adopt this template before it has any application code at all —
|
|
118
172
|
# a fresh Tier B scaffold with decisions locked and a backlog filed, nothing
|
|
119
173
|
# else. Unguarded, every step below still runs: "Install dependencies" warns
|
|
@@ -147,6 +201,31 @@ jobs:
|
|
|
147
201
|
with:
|
|
148
202
|
persist-credentials: false
|
|
149
203
|
|
|
204
|
+
# ---------------------------------------------------------------------------
|
|
205
|
+
# Descriptor check (#416). A value `colab ship` cannot use does not fail there —
|
|
206
|
+
# it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
|
|
207
|
+
# once turned every landing in a busy repo back to serial while this CI stayed
|
|
208
|
+
# green; only a ship dry run noticed. So the value fails HERE, where the person
|
|
209
|
+
# who changed project.yml is looking. Same rule as `colab ship` and the audit
|
|
210
|
+
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
211
|
+
# cap is 3: project.schema.md, `ship-batch`.
|
|
212
|
+
# ---------------------------------------------------------------------------
|
|
213
|
+
- name: Descriptor check (.github/project.yml)
|
|
214
|
+
working-directory: ${{ github.workspace }}
|
|
215
|
+
run: |
|
|
216
|
+
[ -f .github/project.yml ] || exit 0
|
|
217
|
+
line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
|
|
218
|
+
[ -n "$line" ] || exit 0
|
|
219
|
+
v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
|
|
220
|
+
-e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
|
|
221
|
+
-e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
|
|
222
|
+
case "$v" in
|
|
223
|
+
''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
|
|
224
|
+
*)
|
|
225
|
+
echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
|
|
226
|
+
exit 1 ;;
|
|
227
|
+
esac
|
|
228
|
+
|
|
150
229
|
# ---------------------------------------------------------------------------
|
|
151
230
|
# Toolchain resolution. Precedence, highest first:
|
|
152
231
|
# 1. .github/project.yml -> node: <version>
|
package/templates/ci-python.yml
CHANGED
|
@@ -27,6 +27,7 @@
|
|
|
27
27
|
# NOT for: Laravel + Inertia fullstack apps — use ci-laravel.yml.
|
|
28
28
|
#
|
|
29
29
|
# What it does:
|
|
30
|
+
# 0. Fail on a .github/project.yml value colab would silently ignore (ship-batch, #416).
|
|
30
31
|
# 1. Resolve the Python version from declared sources — never a hardcoded default.
|
|
31
32
|
# 2. Secret scan with gitleaks (pinned release binary, see note at the step).
|
|
32
33
|
# 3. Install dependencies from whichever manifest the repo actually has.
|
|
@@ -82,8 +83,59 @@ env:
|
|
|
82
83
|
# jobs from different runs interleave, and trunk can wait behind branch runs.
|
|
83
84
|
# Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
|
|
84
85
|
jobs:
|
|
86
|
+
# Already tested at this sha? (#418) — the claim push.
|
|
87
|
+
# A session's claim pushes its branch at the moment it is cut (CONVENTIONS.md §5, the
|
|
88
|
+
# claim record), so the branch's first push sits on a sha trunk has usually already
|
|
89
|
+
# run. Without this job that push re-runs the whole suite on a tested commit (~19% of
|
|
90
|
+
# all runs, measured across five adopting repos). This job runs ONLY on a ref's first
|
|
91
|
+
# push (`github.event.created`), checks nothing out, and asks one question: does THIS
|
|
92
|
+
# workflow already have a completed, green, non-PR run at THIS exact sha? Yes → every
|
|
93
|
+
# other job is skipped and the run concludes `success` — a branch-CI `green` that is
|
|
94
|
+
# true, because the same workflow passed at the same sha. Anything else — trunk still
|
|
95
|
+
# running, red, never run, `gh` missing, the API failing — and the suite runs as
|
|
96
|
+
# before (fail-open: this job never fails the run). Every later push has
|
|
97
|
+
# `created == false`, so a real commit always gets the full suite, with no extra hop.
|
|
98
|
+
# Why not simply `if: !github.event.created` on every job: a run whose jobs are ALL
|
|
99
|
+
# skipped concludes `skipped`, which `colab ship` reads as not-green (CONVENTIONS.md
|
|
100
|
+
# §4, "Branch CI"). This job is the one that ends green.
|
|
101
|
+
dedupe:
|
|
102
|
+
name: Already tested at this sha?
|
|
103
|
+
if: github.event_name == 'push' && github.event.created
|
|
104
|
+
runs-on: ubuntu-latest # EDIT: the same label as the jobs below; it needs `gh` (GitHub-hosted images have it).
|
|
105
|
+
permissions:
|
|
106
|
+
actions: read
|
|
107
|
+
outputs:
|
|
108
|
+
tested: ${{ steps.check.outputs.tested }}
|
|
109
|
+
steps:
|
|
110
|
+
- name: Look for a green run of this workflow at this sha
|
|
111
|
+
id: check
|
|
112
|
+
env:
|
|
113
|
+
GH_TOKEN: ${{ github.token }}
|
|
114
|
+
REPO: ${{ github.repository }}
|
|
115
|
+
RUN_ID: ${{ github.run_id }}
|
|
116
|
+
SHA: ${{ github.sha }}
|
|
117
|
+
run: |
|
|
118
|
+
tested=false
|
|
119
|
+
if ! command -v gh >/dev/null 2>&1; then
|
|
120
|
+
echo "::notice::gh is not installed on this runner — running the full suite (#418)."
|
|
121
|
+
elif ! WFID="$(gh api "repos/$REPO/actions/runs/$RUN_ID" --jq .workflow_id 2>/dev/null)" || [ -z "$WFID" ]; then
|
|
122
|
+
echo "::notice::Could not read this run's workflow id — running the full suite (#418)."
|
|
123
|
+
elif ! N="$(gh api "repos/$REPO/actions/workflows/$WFID/runs?head_sha=$SHA&status=success&per_page=20" \
|
|
124
|
+
--jq "[.workflow_runs[] | select(.id != $RUN_ID and .event != \"pull_request\")] | length" 2>/dev/null)"; then
|
|
125
|
+
echo "::notice::Could not list this workflow's runs at $SHA — running the full suite (#418)."
|
|
126
|
+
elif [ "${N:-0}" -ge 1 ] 2>/dev/null; then
|
|
127
|
+
tested=true
|
|
128
|
+
echo "This workflow already passed at $SHA ($N green run(s)) — skipping the suite (#418)."
|
|
129
|
+
echo "Already tested: this workflow has a green run at \`$SHA\` — suite skipped (#418)." >> "$GITHUB_STEP_SUMMARY"
|
|
130
|
+
else
|
|
131
|
+
echo "No green run of this workflow at $SHA yet — running the full suite."
|
|
132
|
+
fi
|
|
133
|
+
echo "tested=$tested" >> "$GITHUB_OUTPUT"
|
|
134
|
+
|
|
85
135
|
gitleaks:
|
|
86
136
|
name: Secret scan (gitleaks)
|
|
137
|
+
needs: dedupe
|
|
138
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
87
139
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
88
140
|
steps:
|
|
89
141
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
@@ -128,6 +180,8 @@ jobs:
|
|
|
128
180
|
|
|
129
181
|
build:
|
|
130
182
|
name: Build (Python)
|
|
183
|
+
needs: dedupe
|
|
184
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
131
185
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
132
186
|
defaults:
|
|
133
187
|
run:
|
|
@@ -138,6 +192,31 @@ jobs:
|
|
|
138
192
|
with:
|
|
139
193
|
persist-credentials: false
|
|
140
194
|
|
|
195
|
+
# ---------------------------------------------------------------------------
|
|
196
|
+
# Descriptor check (#416). A value `colab ship` cannot use does not fail there —
|
|
197
|
+
# it fails closed to the safe default, silently. `ship-batch: 5` (the cap is 3)
|
|
198
|
+
# once turned every landing in a busy repo back to serial while this CI stayed
|
|
199
|
+
# green; only a ship dry run noticed. So the value fails HERE, where the person
|
|
200
|
+
# who changed project.yml is looking. Same rule as `colab ship` and the audit
|
|
201
|
+
# (tools/lib/ship-batch.js parseShipBatch): absent/empty/null, or 1–3. Why the
|
|
202
|
+
# cap is 3: project.schema.md, `ship-batch`.
|
|
203
|
+
# ---------------------------------------------------------------------------
|
|
204
|
+
- name: Descriptor check (.github/project.yml)
|
|
205
|
+
working-directory: ${{ github.workspace }}
|
|
206
|
+
run: |
|
|
207
|
+
[ -f .github/project.yml ] || exit 0
|
|
208
|
+
line="$(grep -E '^ship-batch[[:space:]]*:' .github/project.yml | head -1 || true)"
|
|
209
|
+
[ -n "$line" ] || exit 0
|
|
210
|
+
v="$(printf '%s\n' "$line" | sed -E -e 's/^ship-batch[[:space:]]*:[[:space:]]*//' \
|
|
211
|
+
-e 's/[[:space:]]+#.*$//' -e 's/[[:space:]]+$//' \
|
|
212
|
+
-e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
|
|
213
|
+
case "$v" in
|
|
214
|
+
''|'~'|null|1|2|3) echo "ship-batch: ${v:-absent} — ok" ;;
|
|
215
|
+
*)
|
|
216
|
+
echo "::error file=.github/project.yml::ship-batch is '$v', expected an integer 1-3 (omit for serial). colab ship ignores any other value and lands serially. Why the cap is 3: project.schema.md, ship-batch."
|
|
217
|
+
exit 1 ;;
|
|
218
|
+
esac
|
|
219
|
+
|
|
141
220
|
# ---------------------------------------------------------------------------
|
|
142
221
|
# Toolchain resolution. Precedence, highest first:
|
|
143
222
|
# 1. .github/project.yml -> python: <version>
|
package/templates/pre-push-guard
CHANGED
|
@@ -9,10 +9,14 @@
|
|
|
9
9
|
# COLAB_SHIP does NOT open main — ship is trunk/line-only by design.
|
|
10
10
|
# The guard keys on `trunk != main`, never on the tier letter, so tier C is covered
|
|
11
11
|
# automatically — main there is what promotion deploys, so it needs the gate most.
|
|
12
|
+
# RELEASE CHANNELS `next` and `stable` (#445): allowed by COLAB_RELEASE=1 (`colab release cut` moves
|
|
13
|
+
# `next`, `colab release finalize` moves `stable`) or COLAB_HUMAN=1. Nothing else writes them —
|
|
14
|
+
# they name the newest candidate and the newest final, and a hand push makes them lie. A repo that
|
|
15
|
+
# uses a branch of either name for something else edits its copy of this hook (copy-and-own).
|
|
12
16
|
# On tier B (trunk == main) the trunk rule already covers main. Non-protected pushes always pass.
|
|
13
17
|
# Missing .github/project.yml → degrade to ALLOW (with a warning) rather than block work.
|
|
14
18
|
#
|
|
15
|
-
# The
|
|
19
|
+
# The variables named above are set BY A TOOL (`colab ship`, `colab promote`, `colab release`) or BY A PERSON at
|
|
16
20
|
# the keyboard — never by an agent reading this file or one of the refusals below. COLAB_SHIP is a
|
|
17
21
|
# process-identity assertion, not a permission: typed by hand it claims preconditions nothing ran.
|
|
18
22
|
# The refusal messages below therefore name the remedy and not the variable (#322) — this header is
|
|
@@ -51,10 +55,13 @@ integration=$(awk '
|
|
|
51
55
|
pushing_trunk=0
|
|
52
56
|
pushing_main=0
|
|
53
57
|
pushing_line=""
|
|
58
|
+
pushing_channel=""
|
|
54
59
|
while read -r _localref _localsha remoteref _remotesha; do
|
|
55
60
|
case "${remoteref:-}" in
|
|
56
61
|
refs/heads/"$trunk") pushing_trunk=1 ;;
|
|
57
62
|
refs/heads/main) pushing_main=1 ;;
|
|
63
|
+
refs/heads/next) pushing_channel=next ;;
|
|
64
|
+
refs/heads/stable) pushing_channel=stable ;;
|
|
58
65
|
esac
|
|
59
66
|
for line in $integration; do
|
|
60
67
|
if [ "${remoteref:-}" = "refs/heads/$line" ]; then pushing_line="$line"; fi
|
|
@@ -105,6 +112,19 @@ if [ -n "$pushing_line" ] && [ "${COLAB_SHIP:-}" != "1" ] && [ "${COLAB_HUMAN:-}
|
|
|
105
112
|
exit 1
|
|
106
113
|
fi
|
|
107
114
|
|
|
115
|
+
# RELEASE-CHANNEL guard (#445) — `next` / `stable` move only with a release, forward only.
|
|
116
|
+
if [ -n "$pushing_channel" ] && [ "${COLAB_RELEASE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
|
|
117
|
+
echo "pre-push-guard: refusing raw push to release channel '$pushing_channel'." >&2
|
|
118
|
+
echo " It names the newest $( [ "$pushing_channel" = next ] && echo candidate || echo final ) and moves only with one:" >&2
|
|
119
|
+
if [ "$pushing_channel" = next ]; then
|
|
120
|
+
echo " colab release cut # a new candidate fast-forwards 'next'" >&2
|
|
121
|
+
else
|
|
122
|
+
echo " colab release finalize # a new final fast-forwards 'stable'" >&2
|
|
123
|
+
fi
|
|
124
|
+
echo " To follow a different version, pin its tag where you consume it; the channel stays where it is." >&2
|
|
125
|
+
exit 1
|
|
126
|
+
fi
|
|
127
|
+
|
|
108
128
|
# MAIN guard — only on tier A and C (trunk != main). COLAB_SHIP intentionally does NOT open main.
|
|
109
129
|
if [ "$trunk" != "main" ] && [ "$pushing_main" -eq 1 ] && [ "${COLAB_PROMOTE:-}" != "1" ] && [ "${COLAB_HUMAN:-}" != "1" ]; then
|
|
110
130
|
echo "pre-push-guard: refusing raw push to 'main' (promotion target)." >&2
|
|
@@ -124,16 +124,24 @@ concurrency:
|
|
|
124
124
|
permissions: {}
|
|
125
125
|
|
|
126
126
|
env:
|
|
127
|
-
# EDIT: the handbook
|
|
128
|
-
#
|
|
129
|
-
|
|
127
|
+
# EDIT: the handbook ref whose colab CLI makes the release decisions — a CHANNEL or a
|
|
128
|
+
# version tag (CONVENTIONS.md §6, *Release channels*, #445):
|
|
129
|
+
# stable the newest final release — the default; it moves forward as finals are cut,
|
|
130
|
+
# and that release's notes say what changed
|
|
131
|
+
# next the newest candidate (vX.Y.Z-rc.N) — the fast channel
|
|
132
|
+
# vX.Y.Z an exact version tag — frozen; moving it is a deliberate act, like re-copying
|
|
133
|
+
# a template
|
|
134
|
+
HANDBOOK_REF: "stable"
|
|
130
135
|
HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
|
|
131
136
|
|
|
132
137
|
jobs:
|
|
133
138
|
release:
|
|
134
139
|
name: Cut, finalize, publish
|
|
135
|
-
#
|
|
136
|
-
|
|
140
|
+
# No job-level `if:` here, on purpose (#435): a red CI run is gated in the first step below,
|
|
141
|
+
# so this run concludes success. A job-level `if:` would skip every job, GitHub would record
|
|
142
|
+
# the whole run as `skipped` at that main sha, and `colab ship` reads any finished run that is
|
|
143
|
+
# neither success nor cancelled as "not green". Re-run CI green on that sha and the skipped
|
|
144
|
+
# Release (auto) row would still sit beside it, refusing every ship until main moves.
|
|
137
145
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
138
146
|
permissions:
|
|
139
147
|
contents: write # push the tags (and, with promotion: main-loop, the promotion), publish the GitHub Release
|
|
@@ -160,6 +168,23 @@ jobs:
|
|
|
160
168
|
# checkout's origin. The token is this job's, scoped by `permissions:` above.
|
|
161
169
|
persist-credentials: true
|
|
162
170
|
|
|
171
|
+
# A red CI run on main is not a candidate. Gated here rather than by a job-level `if:` so
|
|
172
|
+
# this run concludes success, never `skipped` (#435; the comment on the job above).
|
|
173
|
+
- name: Gate on the triggering CI run
|
|
174
|
+
id: gate
|
|
175
|
+
env:
|
|
176
|
+
EVENT: ${{ github.event_name }}
|
|
177
|
+
CONCLUSION: ${{ github.event.workflow_run.conclusion }}
|
|
178
|
+
HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
|
|
179
|
+
run: |
|
|
180
|
+
set -euo pipefail
|
|
181
|
+
if [ "$EVENT" = "workflow_run" ] && [ "$CONCLUSION" != "success" ]; then
|
|
182
|
+
echo "cut=false" >> "$GITHUB_OUTPUT"
|
|
183
|
+
echo "CI concluded \`$CONCLUSION\` at $HEAD_SHA — nothing to cut." | tee -a "$GITHUB_STEP_SUMMARY"
|
|
184
|
+
else
|
|
185
|
+
echo "cut=true" >> "$GITHUB_OUTPUT"
|
|
186
|
+
fi
|
|
187
|
+
|
|
163
188
|
- name: Fetch the colab CLI
|
|
164
189
|
run: |
|
|
165
190
|
set -euo pipefail
|
|
@@ -214,7 +239,7 @@ jobs:
|
|
|
214
239
|
# right after this run promoted: that head has no CI yet — the dispatched run cuts it.
|
|
215
240
|
- name: Cut a candidate (colab release cut --auto)
|
|
216
241
|
id: cut
|
|
217
|
-
if: (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
|
|
242
|
+
if: steps.gate.outputs.cut == 'true' && (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
|
|
218
243
|
run: |
|
|
219
244
|
set -uo pipefail
|
|
220
245
|
OUT="$RUNNER_TEMP/cut.json"
|