@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.11
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/LICENSE +21 -0
- package/README.md +312 -3
- package/README.vi.md +281 -0
- package/audit/audit.mjs +3035 -0
- package/package.json +26 -5
- package/templates/README.md +257 -0
- package/templates/adr-README.md +57 -0
- package/templates/branch-name.yml +51 -0
- package/templates/ci-laravel.yml +540 -0
- package/templates/ci-node.yml +291 -0
- package/templates/ci-python.yml +281 -0
- package/templates/deploy-xserver.yml +531 -0
- package/templates/dist-refs.yml +177 -0
- package/templates/docs-lint.mjs +993 -0
- package/templates/docs-lint.yml +55 -0
- package/templates/gotchas-d-README.md +41 -0
- package/templates/identity-vocabulary.example +58 -0
- package/templates/npx-launcher.mjs +213 -0
- package/templates/pre-commit-dispatch +88 -0
- package/templates/pre-commit-identity +267 -0
- package/templates/pre-push-guard +137 -0
- package/templates/release-auto.yml +475 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13806 -0
- package/tools/lib/adopt.js +882 -0
- package/tools/lib/axis-authority.js +96 -0
- package/tools/lib/base-ci-verdict.js +93 -0
- package/tools/lib/blocked-by.js +262 -0
- package/tools/lib/branch-name.js +137 -0
- package/tools/lib/checklist.js +143 -0
- package/tools/lib/ci-cure.js +512 -0
- package/tools/lib/ci-grant.js +307 -0
- package/tools/lib/ci-verdict.js +113 -0
- package/tools/lib/claim-comments.js +212 -0
- package/tools/lib/claim-identity.js +195 -0
- package/tools/lib/codeowners.js +208 -0
- package/tools/lib/consumer-evidence.js +74 -0
- package/tools/lib/container-close.js +141 -0
- package/tools/lib/cure-diff.js +267 -0
- package/tools/lib/decision-record.js +335 -0
- package/tools/lib/dirty-owner.js +150 -0
- package/tools/lib/disposition.js +378 -0
- package/tools/lib/docs-only.js +156 -0
- package/tools/lib/exposure-shape.js +207 -0
- package/tools/lib/gate.js +80 -0
- package/tools/lib/git.js +1059 -0
- package/tools/lib/group-labels.js +120 -0
- package/tools/lib/hermetic.js +193 -0
- package/tools/lib/identity.js +187 -0
- package/tools/lib/install-check.js +278 -0
- package/tools/lib/instruction-file.js +302 -0
- package/tools/lib/journal.js +430 -0
- package/tools/lib/labels.js +653 -0
- package/tools/lib/landed.js +230 -0
- package/tools/lib/local-adopt.js +133 -0
- package/tools/lib/lockfile-drift.js +119 -0
- package/tools/lib/machine-trailer.js +83 -0
- package/tools/lib/machine.js +238 -0
- package/tools/lib/migration-grant.js +641 -0
- package/tools/lib/migration-paths.js +135 -0
- package/tools/lib/notify-endpoint.js +170 -0
- package/tools/lib/notify.js +188 -0
- package/tools/lib/npm-publish-guard.js +242 -0
- package/tools/lib/orphan-worktree.js +127 -0
- package/tools/lib/owner-branch.js +182 -0
- package/tools/lib/place.js +782 -0
- package/tools/lib/ports.js +167 -0
- package/tools/lib/procs.js +185 -0
- package/tools/lib/readiness.js +240 -0
- package/tools/lib/records.js +185 -0
- package/tools/lib/refs-brake.js +95 -0
- package/tools/lib/release-channel.js +99 -0
- package/tools/lib/release-cut.js +822 -0
- package/tools/lib/release-finalize.js +521 -0
- package/tools/lib/release-policy.js +358 -0
- package/tools/lib/release-tag.js +225 -0
- package/tools/lib/ship-batch.js +277 -0
- package/tools/lib/ship-roles.js +71 -0
- package/tools/lib/ship-target-sync.js +181 -0
- package/tools/lib/shipguard.js +317 -0
- package/tools/lib/shipped-branch.js +56 -0
- package/tools/lib/solo.js +213 -0
- package/tools/lib/squash.js +515 -0
- package/tools/lib/stale-base.js +70 -0
- package/tools/lib/stamp.js +740 -0
- package/tools/lib/state.js +262 -0
- package/tools/lib/teardown.js +83 -0
- package/tools/lib/trust-humans.js +104 -0
- package/tools/lib/util.js +98 -0
- package/tools/lib/wake.js +188 -0
- package/tools/lib/workflow-triggers.js +273 -0
- package/tools/lib/writes-authority.js +237 -0
- package/tools/lib/yaml.js +101 -0
- package/bin/cli.js +0 -3
|
@@ -0,0 +1,475 @@
|
|
|
1
|
+
# Release (auto) — TEMPLATE. Copy me into your repo at .github/workflows/release-auto.yml.
|
|
2
|
+
#
|
|
3
|
+
# This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
|
|
4
|
+
# Edit it freely; nothing calls it remotely and nothing will update it for you.
|
|
5
|
+
#
|
|
6
|
+
# EDIT POINTS are marked `# EDIT:` — walk them once after copying.
|
|
7
|
+
#
|
|
8
|
+
# WHAT IT DOES. It runs CONVENTIONS.md §6's release rung so nobody has to remember to:
|
|
9
|
+
#
|
|
10
|
+
# trigger step
|
|
11
|
+
# ---------------------------------------- ------------------------------------------------
|
|
12
|
+
# a daily schedule, first colab promote --auto → dev → main, then
|
|
13
|
+
# (`trunk: dev` + `deploy: tag` + CI dispatched on
|
|
14
|
+
# `promotion: main-loop` only; a no-op main (#440)
|
|
15
|
+
# everywhere else)
|
|
16
|
+
# your CI workflow finished green on main colab release cut --auto → vX.Y.Z-rc.N
|
|
17
|
+
# (on `trunk: dev`: the promotion's push), (#443: the newest candidate always names main's
|
|
18
|
+
# and the daily schedule head; a head already carrying one is a no-op)
|
|
19
|
+
# a daily schedule colab release finalize --auto → vX.Y.Z (or a
|
|
20
|
+
# hand-off where
|
|
21
|
+
# the final is a
|
|
22
|
+
# human's)
|
|
23
|
+
# workflow_dispatch all three, in that order
|
|
24
|
+
# any of the above tagged something, and npm publish (job `npm`, #433) — candidates to
|
|
25
|
+
# project.yml declares release.npm dist-tag `next`, finals to `latest`; see the
|
|
26
|
+
# comment above that job
|
|
27
|
+
#
|
|
28
|
+
# Every decision — whether a candidate is owed, which bump, whether the test period
|
|
29
|
+
# elapsed clean, whether the final is automatic on this repo at all — is the colab CLI's,
|
|
30
|
+
# read from .github/project.yml's release rung. This file only schedules it and publishes
|
|
31
|
+
# what it tagged. Where the rung leaves candidates off, every run is a recorded refusal.
|
|
32
|
+
#
|
|
33
|
+
# WHERE IT FITS. `colab release cut` tags origin/main — release tags land on `main` on every
|
|
34
|
+
# trunk shape — so the same file, unchanged, fits two kinds of repo:
|
|
35
|
+
#
|
|
36
|
+
# `trunk: main` + `deploy: tag | none` every green CI run on main may cut a candidate.
|
|
37
|
+
# `trunk: dev` + `deploy: tag` main only moves when dev is promoted into main (by
|
|
38
|
+
# a human, or unattended below), so the green CI run
|
|
39
|
+
# on that promotion is the trigger. The CLI reads `trunk:` and cuts only when
|
|
40
|
+
# main's head IS a promotion of dev (a --no-ff merge
|
|
41
|
+
# whose later parent is on dev, or a fast-forward);
|
|
42
|
+
# any other head — a hotfix straight on main — is a
|
|
43
|
+
# no-op, carried by the next promotion or cut by hand
|
|
44
|
+
# with `colab release cut`. The bump reads the
|
|
45
|
+
# promoted dev commits (never the merge subject, never
|
|
46
|
+
# dev commits not yet promoted), and the manifest
|
|
47
|
+
# version is read on main's promotion commit, so a
|
|
48
|
+
# version bump must reach main through the promotion.
|
|
49
|
+
# Finalize only posts the one-click hand-off: a final
|
|
50
|
+
# is a human act wherever a tag deploys. Needs a
|
|
51
|
+
# HANDBOOK_REF that carries #429; older CLIs cut on
|
|
52
|
+
# any green main head.
|
|
53
|
+
#
|
|
54
|
+
# UNATTENDED PROMOTION (#440). Who may promote is project.yml's `promotion:`, read by the CLI. Where
|
|
55
|
+
# it says `main-loop` — and only on `deploy: tag`, where promotion verifies and deploys nothing —
|
|
56
|
+
# the daily run first runs `colab promote --auto`: when dev's head CI is green and dev is ahead of
|
|
57
|
+
# main it merges dev → main (`--no-ff`) and pushes main, then dispatches your CI workflow on main.
|
|
58
|
+
# The dispatch is needed because a push made with GITHUB_TOKEN triggers no workflow; a
|
|
59
|
+
# workflow_dispatch is the documented exception. That CI run's green completion fires this
|
|
60
|
+
# workflow again, and the cut step cuts the candidate exactly as it does for a human promotion. So
|
|
61
|
+
# your CI workflow must accept `workflow_dispatch:` (the handbook's CI templates do), and main
|
|
62
|
+
# must accept a push from this job's token (a ruleset on main that blocks it turns every promotion
|
|
63
|
+
# into a recorded refusal). Everywhere else — `promotion: human` or absent, `deploy: push-main`,
|
|
64
|
+
# `manual`, `none`, `trunk: main` — the step is a no-op and nothing promotes. The final tag stays
|
|
65
|
+
# the human click. Needs a HANDBOOK_REF that carries #440; an older CLI gives no verdict, which is
|
|
66
|
+
# a warning, never a failed run.
|
|
67
|
+
#
|
|
68
|
+
# Your CI workflow must run on pushes to main for the trigger to fire — the handbook's CI
|
|
69
|
+
# templates run on every branch. It does not fit `exposure: live` (no tags: the promotion
|
|
70
|
+
# itself is the deploy).
|
|
71
|
+
#
|
|
72
|
+
# PUBLISHING HAPPENS IN THIS RUN — deliberately. A tag pushed with GITHUB_TOKEN does NOT
|
|
73
|
+
# trigger other workflows (GitHub suppresses it to prevent loops). So "cut the tag here and
|
|
74
|
+
# let release.yml fire on the tag push" silently does nothing: the tag exists, no Release
|
|
75
|
+
# is ever published. The last step below publishes whatever this run tagged, itself.
|
|
76
|
+
# The same suppression means a deploy workflow on `v*.*.*` does not fire for a tag this
|
|
77
|
+
# workflow pushes either — on a `deploy: tag` repo the final is a human act anyway, and
|
|
78
|
+
# finalize --auto only posts the command for it.
|
|
79
|
+
#
|
|
80
|
+
# IT READS TAGS AND CREATES TAGS. IT NEVER WRITES A COMMIT. No step here commits; the refs
|
|
81
|
+
# pushed are the tags `colab release cut` / `colab release finalize` create (annotated, their
|
|
82
|
+
# checks recorded in the tag message) and — only on a repo granting unattended promotion — the
|
|
83
|
+
# promotion merge `colab promote --auto` pushes to main. The npm job never moves git either. `-rc.N` tags are published as
|
|
84
|
+
# pre-releases, never "Latest". The audit's pre-release deploy-trigger check (#332) still
|
|
85
|
+
# applies to your deploy workflows exactly as before.
|
|
86
|
+
#
|
|
87
|
+
# A REFUSAL IS NOT A FAILURE. `colab release cut --auto` refusing (nothing owed, a check
|
|
88
|
+
# failed) is the ordinary output of most runs; it is printed to the run summary as a
|
|
89
|
+
# warning and the job stays green, so a refusal never paints main red for `colab ship`.
|
|
90
|
+
# Only a run that produced no verdict at all (a crash, gh unusable, bad flags) fails.
|
|
91
|
+
#
|
|
92
|
+
# THE CLI IGNORES THIS WORKFLOW'S OWN RUNS when it reads CI at a commit (GITHUB_WORKFLOW,
|
|
93
|
+
# #425) — otherwise its own in-progress run would read as "CI not finished" forever. So
|
|
94
|
+
# never fold these steps into the workflow that runs your test suite: that suite's runs
|
|
95
|
+
# would be ignored with it.
|
|
96
|
+
#
|
|
97
|
+
# NO TOOLCHAIN RESOLUTION. It runs the colab CLI (zero-dependency Node) on the runner's
|
|
98
|
+
# preinstalled Node and gh. Nothing of your project is built here — except in the opt-in
|
|
99
|
+
# `npm` job, which sets up its own Node for npm's trusted publishing (EDIT point there for
|
|
100
|
+
# a package that needs a build). The npm job needs a HANDBOOK_REF that carries #433; an
|
|
101
|
+
# older CLI gives no npm verdict and nothing is published to npm.
|
|
102
|
+
|
|
103
|
+
name: Release (auto)
|
|
104
|
+
|
|
105
|
+
on:
|
|
106
|
+
workflow_run:
|
|
107
|
+
# EDIT: the `name:` of the workflow that runs your test suite on main.
|
|
108
|
+
workflows: ["CI"]
|
|
109
|
+
types: [completed]
|
|
110
|
+
branches: [main]
|
|
111
|
+
schedule:
|
|
112
|
+
# EDIT: when the daily finalize runs (UTC). Off the hour on purpose — the top of the
|
|
113
|
+
# hour is when scheduled runs queue longest.
|
|
114
|
+
- cron: "17 3 * * *"
|
|
115
|
+
workflow_dispatch:
|
|
116
|
+
|
|
117
|
+
# One release run at a time; a second one waits rather than racing the first for the same
|
|
118
|
+
# candidate number. Never cancelled mid-run: a half-finished run may have pushed a tag
|
|
119
|
+
# without publishing it.
|
|
120
|
+
concurrency:
|
|
121
|
+
group: release-auto
|
|
122
|
+
cancel-in-progress: false
|
|
123
|
+
|
|
124
|
+
permissions: {}
|
|
125
|
+
|
|
126
|
+
env:
|
|
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"
|
|
135
|
+
HANDBOOK_REPO: "https://github.com/futurelastic/colab-handbook.git"
|
|
136
|
+
|
|
137
|
+
jobs:
|
|
138
|
+
release:
|
|
139
|
+
name: Cut, finalize, publish
|
|
140
|
+
# A red CI run on main is not a candidate; skip rather than refuse.
|
|
141
|
+
if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
|
|
142
|
+
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
143
|
+
permissions:
|
|
144
|
+
contents: write # push the tags (and, with promotion: main-loop, the promotion), publish the GitHub Release
|
|
145
|
+
issues: write # finalize opens / comments on / closes the "release: vX.Y.Z" tracking issue
|
|
146
|
+
actions: write # read the runs at a commit (ci-green, full-suite, trunk-green); dispatch CI after a promotion
|
|
147
|
+
# What the npm job below needs (#433) — empty / publish=false unless this run tagged something
|
|
148
|
+
# AND .github/project.yml opts in with release.npm.
|
|
149
|
+
outputs:
|
|
150
|
+
tags: ${{ steps.npm-target.outputs.tags }}
|
|
151
|
+
npm: ${{ steps.npm-target.outputs.publish }}
|
|
152
|
+
npm-dir: ${{ steps.npm-target.outputs.dir }}
|
|
153
|
+
npm-gate: ${{ steps.npm-target.outputs.gate }}
|
|
154
|
+
npm-package: ${{ steps.npm-target.outputs.package }}
|
|
155
|
+
env:
|
|
156
|
+
GH_TOKEN: ${{ github.token }}
|
|
157
|
+
steps:
|
|
158
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
159
|
+
with:
|
|
160
|
+
ref: main
|
|
161
|
+
# Full history plus tags: versions, bumps and "previous final" are all read from
|
|
162
|
+
# git, and the on-trunk check refuses a shallow checkout outright.
|
|
163
|
+
fetch-depth: 0
|
|
164
|
+
# Left on deliberately: `colab release cut` / `finalize` push their tag over the
|
|
165
|
+
# checkout's origin. The token is this job's, scoped by `permissions:` above.
|
|
166
|
+
persist-credentials: true
|
|
167
|
+
|
|
168
|
+
- name: Fetch the colab CLI
|
|
169
|
+
run: |
|
|
170
|
+
set -euo pipefail
|
|
171
|
+
git clone --quiet --depth 1 --branch "$HANDBOOK_REF" "$HANDBOOK_REPO" "$RUNNER_TEMP/colab-handbook"
|
|
172
|
+
echo "COLAB=$RUNNER_TEMP/colab-handbook/tools/colab" >> "$GITHUB_ENV"
|
|
173
|
+
# The tags are annotated; git needs an identity to write one.
|
|
174
|
+
git config user.name "github-actions[bot]"
|
|
175
|
+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
|
|
176
|
+
|
|
177
|
+
# #440: where project.yml grants `promotion: main-loop` on `deploy: tag`, promote a green dev
|
|
178
|
+
# into main, then dispatch CI there — its green run fires this workflow again to cut the
|
|
179
|
+
# candidate. Everywhere else the CLI answers a no-op. A refusal (dev CI not green, a push
|
|
180
|
+
# rejected) is a warning; the job stays green.
|
|
181
|
+
- name: Promote unattended (colab promote --auto)
|
|
182
|
+
id: promote
|
|
183
|
+
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
|
|
184
|
+
env:
|
|
185
|
+
# EDIT: your test-suite workflow — the same one `workflow_run.workflows` names above.
|
|
186
|
+
CI_WORKFLOW: "CI"
|
|
187
|
+
run: |
|
|
188
|
+
set -uo pipefail
|
|
189
|
+
OUT="$RUNNER_TEMP/promote.json"
|
|
190
|
+
rc=0
|
|
191
|
+
node "$COLAB" promote --auto --json > "$OUT" || rc=$?
|
|
192
|
+
if ! jq -e 'has("promoted")' "$OUT" > /dev/null 2>&1; then
|
|
193
|
+
echo "::warning::colab promote --auto gave no verdict (exit $rc; a HANDBOOK_REF older than #440?) — nothing was promoted"
|
|
194
|
+
exit 0
|
|
195
|
+
fi
|
|
196
|
+
{
|
|
197
|
+
echo "### colab promote --auto"
|
|
198
|
+
echo
|
|
199
|
+
jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
200
|
+
echo
|
|
201
|
+
} >> "$GITHUB_STEP_SUMMARY"
|
|
202
|
+
if [ "$(jq -r '.promoted' "$OUT")" = "true" ]; then
|
|
203
|
+
echo "promoted=true" >> "$GITHUB_OUTPUT"
|
|
204
|
+
echo "Promoted to main @ $(jq -r '.sha' "$OUT")" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
205
|
+
if gh workflow run "$CI_WORKFLOW" --ref main; then
|
|
206
|
+
echo "Dispatched $CI_WORKFLOW on main — its green run cuts the candidate." | tee -a "$GITHUB_STEP_SUMMARY"
|
|
207
|
+
else
|
|
208
|
+
echo "::warning::promoted, but could not dispatch $CI_WORKFLOW on main (does it declare workflow_dispatch:?) — run it by hand to cut the candidate"
|
|
209
|
+
fi
|
|
210
|
+
elif [ "$(jq -r '.noop' "$OUT")" = "true" ]; then
|
|
211
|
+
echo "No promotion: $(jq -r '.reason' "$OUT")" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
212
|
+
else
|
|
213
|
+
echo "::warning::colab promote --auto refused: $(jq -r '.reason' "$OUT")"
|
|
214
|
+
fi
|
|
215
|
+
|
|
216
|
+
# #443: the newest candidate always names main's head. The scheduled run cuts too, so a head a
|
|
217
|
+
# declared release.candidates-per-day window held back is tagged once the window ends, even
|
|
218
|
+
# with no new merge to fire workflow_run. A head already carrying a candidate is a no-op. Not
|
|
219
|
+
# right after this run promoted: that head has no CI yet — the dispatched run cuts it.
|
|
220
|
+
- name: Cut a candidate (colab release cut --auto)
|
|
221
|
+
id: cut
|
|
222
|
+
if: (github.event_name == 'workflow_run' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') && steps.promote.outputs.promoted != 'true'
|
|
223
|
+
run: |
|
|
224
|
+
set -uo pipefail
|
|
225
|
+
OUT="$RUNNER_TEMP/cut.json"
|
|
226
|
+
rc=0
|
|
227
|
+
node "$COLAB" release cut --auto --json > "$OUT" || rc=$?
|
|
228
|
+
# A verdict is JSON carrying `ok`; anything else is a run that never decided.
|
|
229
|
+
if ! jq -e 'has("ok")' "$OUT" > /dev/null 2>&1; then
|
|
230
|
+
echo "::error::colab release cut produced no verdict (exit $rc)"
|
|
231
|
+
cat "$OUT"
|
|
232
|
+
exit 1
|
|
233
|
+
fi
|
|
234
|
+
{
|
|
235
|
+
echo "### colab release cut --auto"
|
|
236
|
+
echo
|
|
237
|
+
jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
238
|
+
echo
|
|
239
|
+
} >> "$GITHUB_STEP_SUMMARY"
|
|
240
|
+
if [ "$(jq -r '.created' "$OUT")" = "true" ]; then
|
|
241
|
+
TAG="$(jq -r '.tag' "$OUT")"
|
|
242
|
+
echo "tag=$TAG" >> "$GITHUB_OUTPUT"
|
|
243
|
+
echo "Cut $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
244
|
+
elif [ "$(jq -r '.noop' "$OUT")" = "true" ]; then
|
|
245
|
+
echo "No-op: nothing owed, head already a candidate, inside a declared cadence window, or main's head is not a promotion." | tee -a "$GITHUB_STEP_SUMMARY"
|
|
246
|
+
elif [ "$(jq -r '.ok' "$OUT")" = "true" ]; then
|
|
247
|
+
echo "Verdict ok but nothing created." | tee -a "$GITHUB_STEP_SUMMARY"
|
|
248
|
+
else
|
|
249
|
+
echo "::warning::colab release cut refused: $(jq -r '[.checks[]? | select(.ok | not) | .condition] | join(", ")' "$OUT")"
|
|
250
|
+
fi
|
|
251
|
+
|
|
252
|
+
- name: Finalize the newest clean candidate (colab release finalize --auto)
|
|
253
|
+
id: finalize
|
|
254
|
+
if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
|
|
255
|
+
run: |
|
|
256
|
+
set -uo pipefail
|
|
257
|
+
OUT="$RUNNER_TEMP/finalize.json"
|
|
258
|
+
rc=0
|
|
259
|
+
node "$COLAB" release finalize --auto --json > "$OUT" || rc=$?
|
|
260
|
+
if ! jq -e 'has("state")' "$OUT" > /dev/null 2>&1; then
|
|
261
|
+
echo "::error::colab release finalize produced no verdict (exit $rc)"
|
|
262
|
+
cat "$OUT"
|
|
263
|
+
exit 1
|
|
264
|
+
fi
|
|
265
|
+
STATE="$(jq -r '.state' "$OUT")"
|
|
266
|
+
{
|
|
267
|
+
echo "### colab release finalize --auto — $STATE"
|
|
268
|
+
echo
|
|
269
|
+
jq -r '.checks[]? | "- \(if .ok then "✓" else "✗" end) **\(.condition)** — \(.detail)"' "$OUT"
|
|
270
|
+
echo
|
|
271
|
+
} >> "$GITHUB_STEP_SUMMARY"
|
|
272
|
+
if [ "$(jq -r '.tagged' "$OUT")" = "true" ]; then
|
|
273
|
+
TAG="$(jq -r '.finalTag' "$OUT")"
|
|
274
|
+
echo "tag=$TAG" >> "$GITHUB_OUTPUT"
|
|
275
|
+
echo "Finalized $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
276
|
+
else
|
|
277
|
+
case "$STATE" in
|
|
278
|
+
refused|needs-new-candidate|held) echo "::warning::colab release finalize: $STATE" ;;
|
|
279
|
+
*) echo "Finalize: $STATE" ;;
|
|
280
|
+
esac
|
|
281
|
+
fi
|
|
282
|
+
|
|
283
|
+
# Whether the npm job publishes what this run tagged — `colab release npm` reads the
|
|
284
|
+
# release: block (one reading, the same as cut/finalize). A CLI older than #433 gives no
|
|
285
|
+
# verdict; that is a warning and no npm publish, never a failed release.
|
|
286
|
+
- name: Read the npm target (colab release npm)
|
|
287
|
+
id: npm-target
|
|
288
|
+
if: steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != ''
|
|
289
|
+
env:
|
|
290
|
+
TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
|
|
291
|
+
run: |
|
|
292
|
+
set -uo pipefail
|
|
293
|
+
OUT="$RUNNER_TEMP/npm.json"
|
|
294
|
+
node "$COLAB" release npm --json > "$OUT" 2> /dev/null || true
|
|
295
|
+
if ! jq -e 'has("publish")' "$OUT" > /dev/null 2>&1; then
|
|
296
|
+
echo "::warning::colab release npm gave no verdict (a HANDBOOK_REF older than #433?) — nothing is published to npm"
|
|
297
|
+
echo "publish=false" >> "$GITHUB_OUTPUT"
|
|
298
|
+
exit 0
|
|
299
|
+
fi
|
|
300
|
+
if [ "$(jq -r '.publish' "$OUT")" != "true" ]; then
|
|
301
|
+
if [ "$(jq -r '.findings | length' "$OUT")" != "0" ]; then
|
|
302
|
+
echo "::warning::not publishing to npm: $(jq -r '.findings | join("; ")' "$OUT")"
|
|
303
|
+
fi
|
|
304
|
+
echo "publish=false" >> "$GITHUB_OUTPUT"
|
|
305
|
+
exit 0
|
|
306
|
+
fi
|
|
307
|
+
{
|
|
308
|
+
echo "publish=true"
|
|
309
|
+
echo "tags=$(echo $TAGS)"
|
|
310
|
+
echo "dir=$(jq -r '.dir' "$OUT")"
|
|
311
|
+
echo "gate=$(jq -r '.gate' "$OUT")"
|
|
312
|
+
echo "package=$(jq -r '.package' "$OUT")"
|
|
313
|
+
} >> "$GITHUB_OUTPUT"
|
|
314
|
+
|
|
315
|
+
# Publishes every tag THIS run created. In this run, never via a tag-push workflow:
|
|
316
|
+
# see "PUBLISHING HAPPENS IN THIS RUN" in the header.
|
|
317
|
+
- name: Publish GitHub Release (same run)
|
|
318
|
+
if: steps.cut.outputs.tag != '' || steps.finalize.outputs.tag != ''
|
|
319
|
+
env:
|
|
320
|
+
TAGS: ${{ steps.cut.outputs.tag }} ${{ steps.finalize.outputs.tag }}
|
|
321
|
+
run: |
|
|
322
|
+
set -euo pipefail
|
|
323
|
+
for TAG in $TAGS; do
|
|
324
|
+
if gh release view "$TAG" > /dev/null 2>&1; then
|
|
325
|
+
echo "$TAG already has a Release — skipping"
|
|
326
|
+
continue
|
|
327
|
+
fi
|
|
328
|
+
# Notes since the previous FINAL tag, candidate or final alike — never since an
|
|
329
|
+
# earlier candidate (the same rule as release-tag.yml).
|
|
330
|
+
PREV="$(git describe --tags --abbrev=0 --match 'v*.*.*' --exclude '*-*' "${TAG}^" 2>/dev/null || true)"
|
|
331
|
+
NOTES="$RUNNER_TEMP/notes-$TAG.md"
|
|
332
|
+
if [ -n "$PREV" ]; then
|
|
333
|
+
node "$COLAB" release-notes "${PREV}..${TAG}" --out "$NOTES"
|
|
334
|
+
else
|
|
335
|
+
printf '## %s\n\nFirst release.\n' "$TAG" > "$NOTES"
|
|
336
|
+
fi
|
|
337
|
+
case "$TAG" in
|
|
338
|
+
*-*) KIND=(--prerelease --latest=false) ;;
|
|
339
|
+
*) KIND=(--latest) ;;
|
|
340
|
+
esac
|
|
341
|
+
gh release create "$TAG" --verify-tag --title "$TAG" --notes-file "$NOTES" --generate-notes "${KIND[@]}"
|
|
342
|
+
echo "Published $TAG" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
343
|
+
done
|
|
344
|
+
|
|
345
|
+
# ---------------------------------------------------------------------------------------------
|
|
346
|
+
# npm (#433) — publishes what the release job tagged, in this same run. Opt-in: it runs only when
|
|
347
|
+
# .github/project.yml declares release.npm + release.npm-gate on the public-tool route, so a repo
|
|
348
|
+
# without them never gets this job.
|
|
349
|
+
#
|
|
350
|
+
# candidate vX.Y.Z-rc.N -> npm publish --tag next --provenance
|
|
351
|
+
# final vX.Y.Z -> npm publish --tag latest --provenance (latest never moves to an rc)
|
|
352
|
+
#
|
|
353
|
+
# TRUSTED PUBLISHING (OIDC) ONLY. No npm token is stored, read, or offered as a fallback — the
|
|
354
|
+
# job refuses to run with one in its environment. npm ends direct publishing with 2FA-bypass
|
|
355
|
+
# tokens in January 2027; this design never used one. One-time setup on npmjs.com: the package's
|
|
356
|
+
# Settings -> Trusted publishing -> GitHub Actions, this repository, workflow file
|
|
357
|
+
# `release-auto.yml` (the file's name, not its `name:`).
|
|
358
|
+
#
|
|
359
|
+
# GITHUB-HOSTED, ALWAYS. npm trusted publishing does not support self-hosted runners, so this job
|
|
360
|
+
# stays on GitHub-hosted even where `release` above runs self-hosted (free on a public repo — the
|
|
361
|
+
# only kind that publishes here; a private repo is refused outright, #432).
|
|
362
|
+
#
|
|
363
|
+
# IT NEVER MOVES GIT. It checks out the tag, stamps the version from the tag into package.json
|
|
364
|
+
# (the manifest carries none — the tag is the version), runs the gate, publishes. Nothing is
|
|
365
|
+
# committed or pushed. If it fails, the tag stands, `npm-record` writes "tagged, not published"
|
|
366
|
+
# on the Release, and re-running the failed job publishes the existing tag; a version already on
|
|
367
|
+
# npm is skipped, so a re-run never double-publishes.
|
|
368
|
+
npm:
|
|
369
|
+
name: Publish to npm (trusted publishing)
|
|
370
|
+
needs: release
|
|
371
|
+
if: needs.release.outputs.npm == 'true'
|
|
372
|
+
runs-on: ubuntu-latest # NEVER self-hosted: npm trusted publishing does not support it.
|
|
373
|
+
permissions:
|
|
374
|
+
contents: read # check out the tag; read the repository's visibility
|
|
375
|
+
id-token: write # the OIDC token npm exchanges for a one-time publish credential
|
|
376
|
+
env:
|
|
377
|
+
GH_TOKEN: ${{ github.token }}
|
|
378
|
+
REPO: ${{ github.repository }}
|
|
379
|
+
TAGS: ${{ needs.release.outputs.tags }}
|
|
380
|
+
PKG_DIR: ${{ needs.release.outputs.npm-dir }}
|
|
381
|
+
GATE: ${{ needs.release.outputs.npm-gate }}
|
|
382
|
+
PACKAGE: ${{ needs.release.outputs.npm-package }}
|
|
383
|
+
steps:
|
|
384
|
+
- name: Refuse a private repository, and any npm token
|
|
385
|
+
run: |
|
|
386
|
+
set -uo pipefail
|
|
387
|
+
# Visibility from the API, never assumed: unknown is refused like private.
|
|
388
|
+
PRIVATE="$(gh api "repos/$REPO" --jq '.private' 2> /dev/null || echo unknown)"
|
|
389
|
+
if [ "$PRIVATE" != "false" ]; then
|
|
390
|
+
echo "::error::$REPO is private (or its visibility could not be read: $PRIVATE) — a private repository never publishes to public npm (#432). Remove release.npm, or install from git."
|
|
391
|
+
exit 1
|
|
392
|
+
fi
|
|
393
|
+
if [ -n "${NODE_AUTH_TOKEN:-}${NPM_TOKEN:-}" ]; then
|
|
394
|
+
echo "::error::an npm token is set in this job's environment — this workflow publishes through trusted publishing (OIDC) only and never with a token. Remove it."
|
|
395
|
+
exit 1
|
|
396
|
+
fi
|
|
397
|
+
|
|
398
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
399
|
+
with:
|
|
400
|
+
fetch-depth: 0
|
|
401
|
+
persist-credentials: false # nothing here pushes
|
|
402
|
+
|
|
403
|
+
- uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
|
|
404
|
+
with:
|
|
405
|
+
node-version: 24 # no registry-url: that writes an .npmrc expecting a token
|
|
406
|
+
|
|
407
|
+
- name: npm new enough for trusted publishing (>= 11.5.1)
|
|
408
|
+
run: |
|
|
409
|
+
set -euo pipefail
|
|
410
|
+
if ! node -e 'const [a,b,c]=process.argv[1].split(".").map(Number);process.exit(a>11||(a===11&&(b>5||(b===5&&c>=1)))?0:1)' "$(npm --version)"; then
|
|
411
|
+
npm install --global npm@11
|
|
412
|
+
fi
|
|
413
|
+
npm --version
|
|
414
|
+
|
|
415
|
+
# EDIT: a package that needs a build step builds here, BEFORE the gate — the gate measures
|
|
416
|
+
# what ships, and the publish below runs with --ignore-scripts so nothing changes after it.
|
|
417
|
+
- name: Publish each tag (npm publish --provenance)
|
|
418
|
+
run: |
|
|
419
|
+
set -euo pipefail
|
|
420
|
+
for TAG in $TAGS; do
|
|
421
|
+
VERSION="${TAG#v}"
|
|
422
|
+
case "$VERSION" in
|
|
423
|
+
*-*) DIST=next ;;
|
|
424
|
+
*) DIST=latest ;;
|
|
425
|
+
esac
|
|
426
|
+
if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
|
|
427
|
+
echo "$PACKAGE@$VERSION is already on npm — skipping" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
428
|
+
continue
|
|
429
|
+
fi
|
|
430
|
+
git checkout --quiet --force "refs/tags/$TAG"
|
|
431
|
+
git clean -fdxq
|
|
432
|
+
(cd "$PKG_DIR" && npm pkg set "version=$VERSION")
|
|
433
|
+
sh -c "$GATE"
|
|
434
|
+
(cd "$PKG_DIR" && npm publish --tag "$DIST" --provenance --access public --ignore-scripts)
|
|
435
|
+
echo "Published $PACKAGE@$VERSION to npm (dist-tag $DIST)" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
436
|
+
done
|
|
437
|
+
|
|
438
|
+
# Writes the npm outcome onto each GitHub Release the run published, replacing its own earlier
|
|
439
|
+
# line on a re-run: "published" once it is, "tagged, not published" with the re-run hint until then.
|
|
440
|
+
npm-record:
|
|
441
|
+
name: Record the npm outcome on the Release
|
|
442
|
+
needs: [release, npm]
|
|
443
|
+
if: always() && needs.release.outputs.npm == 'true'
|
|
444
|
+
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
445
|
+
permissions:
|
|
446
|
+
contents: write # edit the Release notes
|
|
447
|
+
env:
|
|
448
|
+
GH_TOKEN: ${{ github.token }}
|
|
449
|
+
REPO: ${{ github.repository }}
|
|
450
|
+
TAGS: ${{ needs.release.outputs.tags }}
|
|
451
|
+
PACKAGE: ${{ needs.release.outputs.npm-package }}
|
|
452
|
+
RESULT: ${{ needs.npm.result }}
|
|
453
|
+
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
|
|
454
|
+
steps:
|
|
455
|
+
- name: Record the npm outcome
|
|
456
|
+
run: |
|
|
457
|
+
set -euo pipefail
|
|
458
|
+
for TAG in $TAGS; do
|
|
459
|
+
BODY="$(gh release view "$TAG" --repo "$REPO" --json body --jq '.body' 2> /dev/null)" || {
|
|
460
|
+
echo "$TAG has no Release — nothing to record on"
|
|
461
|
+
continue
|
|
462
|
+
}
|
|
463
|
+
VERSION="${TAG#v}"
|
|
464
|
+
case "$VERSION" in *-*) DIST=next ;; *) DIST=latest ;; esac
|
|
465
|
+
if [ "$RESULT" = "success" ]; then
|
|
466
|
+
LINE="npm: published \`$PACKAGE@$VERSION\` (dist-tag \`$DIST\`)."
|
|
467
|
+
else
|
|
468
|
+
LINE="**npm: tagged, not published** (\`$PACKAGE@$VERSION\`, job $RESULT). Re-run the failed \`npm\` job of $RUN_URL — it publishes this existing tag; nothing in git moves."
|
|
469
|
+
fi
|
|
470
|
+
NOTES="$RUNNER_TEMP/notes-$TAG.md"
|
|
471
|
+
printf '%s\n' "$BODY" | sed '/^<!-- colab:npm -->$/,/^<!-- \/colab:npm -->$/d' > "$NOTES"
|
|
472
|
+
printf '\n<!-- colab:npm -->\n%s\n<!-- /colab:npm -->\n' "$LINE" >> "$NOTES"
|
|
473
|
+
gh release edit "$TAG" --repo "$REPO" --notes-file "$NOTES" > /dev/null
|
|
474
|
+
echo "$TAG: $LINE" | tee -a "$GITHUB_STEP_SUMMARY"
|
|
475
|
+
done
|