@futurelastic/colab-handbook 0.0.0-bootstrap.0 → 1.12.0-rc.8
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 +309 -3
- package/README.vi.md +279 -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 +117 -0
- package/templates/release-auto.yml +470 -0
- package/templates/release-tag.yml +245 -0
- package/templates/repo-CLAUDE-block.md +21 -0
- package/tools/colab +13746 -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 +259 -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.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-cut.js +822 -0
- package/tools/lib/release-finalize.js +481 -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 +703 -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,291 @@
|
|
|
1
|
+
# CI (Node) — TEMPLATE. Copy me into your repo at .github/workflows/ci.yml.
|
|
2
|
+
#
|
|
3
|
+
# This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
|
|
4
|
+
# Edit it freely: rename jobs, add steps, drop the parts you do not need. Nothing
|
|
5
|
+
# calls this file remotely and nothing will update it for you — divergence between
|
|
6
|
+
# your copy and the handbook is expected and fine. If you find an improvement worth
|
|
7
|
+
# sharing, change the handbook template too, but that is a manual, deliberate act.
|
|
8
|
+
#
|
|
9
|
+
# EDIT POINTS are marked `# EDIT:` — walk them once after copying.
|
|
10
|
+
#
|
|
11
|
+
# For: pure Node projects (Vite SPA, node libs, Astro static sites, Capacitor apps).
|
|
12
|
+
# NOT for: Laravel + Inertia fullstack apps — their Vite build shells out to
|
|
13
|
+
# `php artisan wayfinder:generate` and needs PHP on the runner. Use ci-laravel.yml.
|
|
14
|
+
#
|
|
15
|
+
# What it does:
|
|
16
|
+
# 1. Resolve the Node version from declared sources — never a hardcoded default.
|
|
17
|
+
# 2. Secret scan with gitleaks (pinned release binary, see note at the step).
|
|
18
|
+
# 3. Install dependencies with the package manager the lockfile implies.
|
|
19
|
+
# 4. Run typecheck / lint / test only if package.json declares those scripts, so a
|
|
20
|
+
# repo without them is not forced to add placeholders to keep CI green.
|
|
21
|
+
# 5. Build.
|
|
22
|
+
|
|
23
|
+
name: CI
|
|
24
|
+
|
|
25
|
+
on:
|
|
26
|
+
push:
|
|
27
|
+
# Every branch, not only trunk (#384). Sessions push branches without opening a
|
|
28
|
+
# PR, so a trunk-only trigger leaves a candidate with no run of its own before the
|
|
29
|
+
# merge: its first run is the post-merge trunk run, and a red there is everyone's
|
|
30
|
+
# TRUNK RED instead of one implementer's hand-back (CONVENTIONS.md §4, "Branch
|
|
31
|
+
# CI"). '**' also covers `ship-batch/**`, the batch-landing opt-in.
|
|
32
|
+
#
|
|
33
|
+
# EDIT: on ONE self-hosted agent shared with trunk, go back to trunk-only until
|
|
34
|
+
# trunk has its own lane — branch runs queue ahead of the one trunk run a merge
|
|
35
|
+
# waits for (CONVENTIONS.md §7, "Self-hosted runners", #355). GitHub-hosted
|
|
36
|
+
# runners, a runner pool, or a trunk-only label picked in `runs-on` on
|
|
37
|
+
# github.ref all have that capacity; keep '**' there. Trunk-only means the
|
|
38
|
+
# branches this repo actually has — and never drop `dev` on a Tier A or C repo:
|
|
39
|
+
# dev is the trunk, so a main-only trigger runs zero checks on the branch you
|
|
40
|
+
# merge into, and nothing looks broken (CONVENTIONS.md §7).
|
|
41
|
+
branches: ['**']
|
|
42
|
+
pull_request:
|
|
43
|
+
# EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
|
|
44
|
+
# trunk, main the release; Tier B: main only).
|
|
45
|
+
branches: [main, dev]
|
|
46
|
+
# A promotion pushed by the release workflow's token triggers no push run, so that workflow
|
|
47
|
+
# dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
|
|
48
|
+
workflow_dispatch:
|
|
49
|
+
|
|
50
|
+
# One live run per branch: a new push cancels the superseded run on the same ref.
|
|
51
|
+
# Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
|
|
52
|
+
# is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). Pull-request runs
|
|
53
|
+
# group under refs/pull/<n>/merge, apart from the branch's push runs.
|
|
54
|
+
# EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
|
|
55
|
+
# may carry any name; one left off this list gets its trunk runs cancelled.
|
|
56
|
+
concurrency:
|
|
57
|
+
group: ci-${{ github.ref }}
|
|
58
|
+
cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
|
|
59
|
+
|
|
60
|
+
env:
|
|
61
|
+
# EDIT: bump deliberately, not automatically.
|
|
62
|
+
GITLEAKS_VERSION: "8.30.1"
|
|
63
|
+
# EDIT: npm script to build. Change for monorepos or non-standard scripts.
|
|
64
|
+
BUILD_COMMAND: "build"
|
|
65
|
+
|
|
66
|
+
# Self-hosted runner? The job layout below assumes GitHub-hosted capacity — a
|
|
67
|
+
# fresh machine per job. With few self-hosted agents every job is a queue slot,
|
|
68
|
+
# jobs from different runs interleave, and trunk can wait behind branch runs.
|
|
69
|
+
# Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
|
|
70
|
+
jobs:
|
|
71
|
+
gitleaks:
|
|
72
|
+
name: Secret scan (gitleaks)
|
|
73
|
+
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
74
|
+
steps:
|
|
75
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
76
|
+
with:
|
|
77
|
+
# Full history: gitleaks scans commits, not just the working tree, so a
|
|
78
|
+
# secret that was committed and later removed is still caught.
|
|
79
|
+
fetch-depth: 0
|
|
80
|
+
persist-credentials: false
|
|
81
|
+
|
|
82
|
+
- name: Install gitleaks (pinned release binary)
|
|
83
|
+
run: |
|
|
84
|
+
# Deliberately NOT gitleaks/gitleaks-action@v2: that action requires a paid
|
|
85
|
+
# GITLEAKS_LICENSE for repositories owned by an organization (free only for
|
|
86
|
+
# personal repos). The release binary itself is MIT and has no such gate.
|
|
87
|
+
# Repos also carry a local pre-commit gitleaks hook; this is the second layer.
|
|
88
|
+
# The asset is OS/arch-specific, so resolve both from uname instead of
|
|
89
|
+
# assuming the GitHub-hosted default: a hardcoded linux_x64 binary on a
|
|
90
|
+
# macOS self-hosted runner is an ELF the kernel cannot exec, and the step
|
|
91
|
+
# fails with exit 126 rather than anything mentioning the platform.
|
|
92
|
+
case "$(uname -s)" in
|
|
93
|
+
Darwin) os=darwin ;;
|
|
94
|
+
Linux) os=linux ;;
|
|
95
|
+
*) echo "unsupported OS: $(uname -s)" >&2; exit 1 ;;
|
|
96
|
+
esac
|
|
97
|
+
case "$(uname -m)" in
|
|
98
|
+
arm64|aarch64) arch=arm64 ;;
|
|
99
|
+
x86_64|amd64) arch=x64 ;;
|
|
100
|
+
*) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
|
|
101
|
+
esac
|
|
102
|
+
curl -sSL -o gitleaks.tar.gz \
|
|
103
|
+
"https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
|
|
104
|
+
# Into $RUNNER_TEMP, not /usr/local/bin: no sudo, no global write — the same
|
|
105
|
+
# step then works on BOTH GitHub-hosted and shared self-hosted runners
|
|
106
|
+
# (a shared runner is infrastructure; jobs must not mutate it).
|
|
107
|
+
tar -xzf gitleaks.tar.gz -C "$RUNNER_TEMP" gitleaks
|
|
108
|
+
chmod +x "$RUNNER_TEMP/gitleaks"
|
|
109
|
+
echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
|
|
110
|
+
rm -f gitleaks.tar.gz
|
|
111
|
+
|
|
112
|
+
- name: gitleaks detect
|
|
113
|
+
run: gitleaks detect --source . --no-banner
|
|
114
|
+
|
|
115
|
+
build:
|
|
116
|
+
name: Build
|
|
117
|
+
# A repo can adopt this template before it has any application code at all —
|
|
118
|
+
# a fresh Tier B scaffold with decisions locked and a backlog filed, nothing
|
|
119
|
+
# else. Unguarded, every step below still runs: "Install dependencies" warns
|
|
120
|
+
# and falls through to `npm install` with no package.json to install, then
|
|
121
|
+
# "Build" fails outright trying to read it — turning trunk CI red as the
|
|
122
|
+
# first consequence of adopting, not of anything about the repo changing.
|
|
123
|
+
# Skip the package.json-dependent steps instead, the same way the generic
|
|
124
|
+
# scaffold workflow guards it (`if [ -f package.json ]; then node=true; else
|
|
125
|
+
# node=false; fi`). gitleaks above stays unconditional — a repo with no code
|
|
126
|
+
# can still commit a secret.
|
|
127
|
+
#
|
|
128
|
+
# NOTE (#245): this guard used to sit here, at job level — `if:
|
|
129
|
+
# hashFiles('package.json') != ''`. `hashFiles()` is NOT among the functions
|
|
130
|
+
# GitHub allows in `jobs.<job_id>.if` (only `github` / `needs` / `vars` /
|
|
131
|
+
# `inputs` plus always()/cancelled()/success()/failure()); a job-level `if:`
|
|
132
|
+
# using it is rejected at workflow-VALIDATION time, before any job runs — the
|
|
133
|
+
# whole workflow file fails with "0 jobs created" and a message that names
|
|
134
|
+
# neither the key nor the expression. It is valid in a step-level `if:`,
|
|
135
|
+
# which is why it looked right when written (a042cea, fixing #73). Moved the
|
|
136
|
+
# guard onto every step below that assumes package.json exists instead — the
|
|
137
|
+
# workspace isn't even checked out yet at job level, so a job-level
|
|
138
|
+
# hashFiles() would have been testing an empty directory even if it were
|
|
139
|
+
# allowed.
|
|
140
|
+
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
141
|
+
defaults:
|
|
142
|
+
run:
|
|
143
|
+
# EDIT: set to the directory holding package.json if the app is not at the root.
|
|
144
|
+
working-directory: .
|
|
145
|
+
steps:
|
|
146
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
147
|
+
with:
|
|
148
|
+
persist-credentials: false
|
|
149
|
+
|
|
150
|
+
# ---------------------------------------------------------------------------
|
|
151
|
+
# Toolchain resolution. Precedence, highest first:
|
|
152
|
+
# 1. .github/project.yml -> node: <version>
|
|
153
|
+
# 2. .nvmrc, else package.json -> engines.node
|
|
154
|
+
# 3. FAIL.
|
|
155
|
+
#
|
|
156
|
+
# There is deliberately NO fallback default. A silent default is exactly how a
|
|
157
|
+
# repo here ended up building on Node 20 in CI while deploying on Node 22 —
|
|
158
|
+
# CI was green and proved nothing about what actually shipped. If the version
|
|
159
|
+
# is not declared anywhere, that is a bug in the repo, and the build says so.
|
|
160
|
+
# ---------------------------------------------------------------------------
|
|
161
|
+
- name: Resolve Node version
|
|
162
|
+
id: toolchain
|
|
163
|
+
if: hashFiles('package.json') != ''
|
|
164
|
+
run: |
|
|
165
|
+
set -euo pipefail
|
|
166
|
+
|
|
167
|
+
# Normalise "^22", ">=22.1", "v22", "22.x" -> "22.1" / "22". setup-node
|
|
168
|
+
# accepts a partial version and picks the newest matching release.
|
|
169
|
+
normalise() {
|
|
170
|
+
printf '%s' "$1" \
|
|
171
|
+
| tr -d '"' \
|
|
172
|
+
| sed -E 's/^[^0-9]*//' \
|
|
173
|
+
| sed -E 's/[[:space:]].*$//' \
|
|
174
|
+
| sed -E 's/\.x$//' \
|
|
175
|
+
| sed -E 's/[^0-9.].*$//' \
|
|
176
|
+
| sed -E 's/\.$//'
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
NODE_VERSION=""
|
|
180
|
+
SOURCE=""
|
|
181
|
+
|
|
182
|
+
# 1. project.yml wins. Flat `node: 22` mapping; good enough, this file is
|
|
183
|
+
# a handful of keys by design.
|
|
184
|
+
if [ -f .github/project.yml ]; then
|
|
185
|
+
V="$(sed -nE 's/^[[:space:]]*node:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml | head -1 || true)"
|
|
186
|
+
if [ -n "$V" ] && [ "$V" != "null" ]; then
|
|
187
|
+
NODE_VERSION="$(normalise "$V")"; SOURCE=".github/project.yml (node:)"
|
|
188
|
+
fi
|
|
189
|
+
fi
|
|
190
|
+
|
|
191
|
+
# 2a. .nvmrc
|
|
192
|
+
if [ -z "$NODE_VERSION" ] && [ -f .nvmrc ]; then
|
|
193
|
+
V="$(grep -vE '^[[:space:]]*(#|$)' .nvmrc | head -1 | tr -d '[:space:]' || true)"
|
|
194
|
+
if [ -n "$V" ]; then
|
|
195
|
+
NODE_VERSION="$(normalise "$V")"; SOURCE=".nvmrc"
|
|
196
|
+
fi
|
|
197
|
+
fi
|
|
198
|
+
|
|
199
|
+
# 2b. package.json -> engines.node
|
|
200
|
+
if [ -z "$NODE_VERSION" ] && [ -f package.json ]; then
|
|
201
|
+
V=""
|
|
202
|
+
if command -v node >/dev/null 2>&1; then
|
|
203
|
+
V="$(node -e "try{const e=require('./package.json').engines||{};process.stdout.write(String(e.node||''))}catch(_){}" || true)"
|
|
204
|
+
elif command -v python3 >/dev/null 2>&1; then
|
|
205
|
+
V="$(python3 -c "import json;print((json.load(open('package.json')).get('engines') or {}).get('node') or '')" || true)"
|
|
206
|
+
fi
|
|
207
|
+
if [ -n "$V" ]; then
|
|
208
|
+
NODE_VERSION="$(normalise "$V")"; SOURCE="package.json (engines.node)"
|
|
209
|
+
fi
|
|
210
|
+
fi
|
|
211
|
+
|
|
212
|
+
# 3. No declared source -> stop. Do not guess.
|
|
213
|
+
if [ -z "$NODE_VERSION" ]; then
|
|
214
|
+
echo "::error::No Node version is declared in this repository, and this workflow refuses to guess one."
|
|
215
|
+
{
|
|
216
|
+
echo ""
|
|
217
|
+
echo "Declare it in ONE of these places (checked in this order):"
|
|
218
|
+
echo " 1. .github/project.yml -> node: \"22\" (preferred: one descriptor for the whole repo)"
|
|
219
|
+
echo " 2. .nvmrc -> 22 (also drives local dev via nvm/fnm)"
|
|
220
|
+
echo " or package.json -> \"engines\": { \"node\": \">=22\" }"
|
|
221
|
+
echo ""
|
|
222
|
+
echo "Pick the version your DEPLOY target runs. CI on a different major than"
|
|
223
|
+
echo "production proves nothing."
|
|
224
|
+
} >&2
|
|
225
|
+
exit 1
|
|
226
|
+
fi
|
|
227
|
+
|
|
228
|
+
echo "node-version=$NODE_VERSION" >> "$GITHUB_OUTPUT"
|
|
229
|
+
echo "Node $NODE_VERSION (resolved from: $SOURCE)"
|
|
230
|
+
echo "Node **$NODE_VERSION** — resolved from \`$SOURCE\`" >> "$GITHUB_STEP_SUMMARY"
|
|
231
|
+
|
|
232
|
+
- name: Setup Node
|
|
233
|
+
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
|
|
234
|
+
if: hashFiles('package.json') != ''
|
|
235
|
+
with:
|
|
236
|
+
node-version: ${{ steps.toolchain.outputs.node-version }}
|
|
237
|
+
|
|
238
|
+
- name: Install dependencies
|
|
239
|
+
if: hashFiles('package.json') != ''
|
|
240
|
+
run: |
|
|
241
|
+
# Lockfile decides the package manager. `npm ci` / `--frozen-lockfile` are
|
|
242
|
+
# intentional: CI must fail on a stale lockfile rather than silently resolve
|
|
243
|
+
# a different dependency tree than the developer had.
|
|
244
|
+
if [ -f pnpm-lock.yaml ]; then
|
|
245
|
+
corepack enable
|
|
246
|
+
pnpm install --frozen-lockfile
|
|
247
|
+
elif [ -f package-lock.json ]; then
|
|
248
|
+
npm ci
|
|
249
|
+
else
|
|
250
|
+
echo "::warning::No lockfile found — falling back to 'npm install'. Commit a lockfile so CI is reproducible."
|
|
251
|
+
npm install
|
|
252
|
+
fi
|
|
253
|
+
|
|
254
|
+
- name: Detect optional scripts
|
|
255
|
+
id: scripts
|
|
256
|
+
if: hashFiles('package.json') != ''
|
|
257
|
+
run: |
|
|
258
|
+
# package.json's `scripts` decides what this job MEASURES: a missing script
|
|
259
|
+
# skips its step and the job still concludes success. So `colab ship`'s cure
|
|
260
|
+
# rule treats a scripts change as an instrument change and never lets such a
|
|
261
|
+
# branch cure a red trunk by itself (CONVENTIONS.md, Cure rule, condition 5).
|
|
262
|
+
#
|
|
263
|
+
# node -e over grep: package.json is JSON, and a "typecheck" substring can
|
|
264
|
+
# appear inside a dependency name or another script's body.
|
|
265
|
+
has() {
|
|
266
|
+
node -e "const s=(require('./package.json').scripts)||{};process.exit(s['$1']?0:1)" 2>/dev/null
|
|
267
|
+
}
|
|
268
|
+
for s in typecheck lint test; do
|
|
269
|
+
if has "$s"; then
|
|
270
|
+
echo "$s=true" >> "$GITHUB_OUTPUT"
|
|
271
|
+
else
|
|
272
|
+
echo "$s=false" >> "$GITHUB_OUTPUT"
|
|
273
|
+
echo "::notice::No '$s' script in package.json — skipping."
|
|
274
|
+
fi
|
|
275
|
+
done
|
|
276
|
+
|
|
277
|
+
- name: Typecheck
|
|
278
|
+
if: steps.scripts.outputs.typecheck == 'true'
|
|
279
|
+
run: npm run typecheck
|
|
280
|
+
|
|
281
|
+
- name: Lint
|
|
282
|
+
if: steps.scripts.outputs.lint == 'true'
|
|
283
|
+
run: npm run lint
|
|
284
|
+
|
|
285
|
+
- name: Test
|
|
286
|
+
if: steps.scripts.outputs.test == 'true'
|
|
287
|
+
run: npm test
|
|
288
|
+
|
|
289
|
+
- name: Build
|
|
290
|
+
if: hashFiles('package.json') != ''
|
|
291
|
+
run: npm run "$BUILD_COMMAND"
|
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
# CI (Python) — TEMPLATE. Copy me into your repo at .github/workflows/ci.yml.
|
|
2
|
+
#
|
|
3
|
+
# This is a starting point, not a dependency. Once you copy it, YOU OWN THIS FILE.
|
|
4
|
+
# Edit it freely: rename jobs, add steps, drop the parts you do not need. Nothing
|
|
5
|
+
# calls this file remotely and nothing will update it for you — divergence between
|
|
6
|
+
# your copy and the handbook is expected and fine. If you find an improvement worth
|
|
7
|
+
# sharing, change the handbook template too, but that is a manual, deliberate act.
|
|
8
|
+
#
|
|
9
|
+
# EDIT POINTS are marked `# EDIT:` — walk them once after copying.
|
|
10
|
+
#
|
|
11
|
+
# For: Python projects — FastAPI/Flask services, CLI tools, libraries.
|
|
12
|
+
#
|
|
13
|
+
# HYBRID REPOS (a Python backend plus a Node/Vite frontend in one repo) are a real
|
|
14
|
+
# and common shape here, and this template covers HALF of one. Do not copy the Node
|
|
15
|
+
# template and graft a Python job into it: the header then lies about what the file
|
|
16
|
+
# is, and that is exactly how a repo ended up with `python-version: "3.13"` hardcoded
|
|
17
|
+
# — the Node template's own rule 1 forbids hardcoding, but there was nowhere to
|
|
18
|
+
# declare a Python version, so the repo had no honest alternative. Instead:
|
|
19
|
+
#
|
|
20
|
+
# 1. copy THIS file to .github/workflows/ci.yml,
|
|
21
|
+
# 2. copy the `build:` job out of ci-node.yml and paste it in alongside,
|
|
22
|
+
# 3. keep BOTH "Resolve … version" steps — each ecosystem resolves independently,
|
|
23
|
+
# and neither may be hardcoded,
|
|
24
|
+
# 4. stamp the file with whichever template you copied first, and say in a comment
|
|
25
|
+
# that the other job came from the other template.
|
|
26
|
+
#
|
|
27
|
+
# NOT for: Laravel + Inertia fullstack apps — use ci-laravel.yml.
|
|
28
|
+
#
|
|
29
|
+
# What it does:
|
|
30
|
+
# 1. Resolve the Python version from declared sources — never a hardcoded default.
|
|
31
|
+
# 2. Secret scan with gitleaks (pinned release binary, see note at the step).
|
|
32
|
+
# 3. Install dependencies from whichever manifest the repo actually has.
|
|
33
|
+
# 4. Byte-compile — the cheapest possible "does it even parse" gate.
|
|
34
|
+
# 5. Run lint / tests only if the repo has them, so a repo without a suite is not
|
|
35
|
+
# forced to add placeholders to keep CI green.
|
|
36
|
+
|
|
37
|
+
name: CI
|
|
38
|
+
|
|
39
|
+
on:
|
|
40
|
+
push:
|
|
41
|
+
# Every branch, not only trunk (#384). Sessions push branches without opening a
|
|
42
|
+
# PR, so a trunk-only trigger leaves a candidate with no run of its own before the
|
|
43
|
+
# merge: its first run is the post-merge trunk run, and a red there is everyone's
|
|
44
|
+
# TRUNK RED instead of one implementer's hand-back (CONVENTIONS.md §4, "Branch
|
|
45
|
+
# CI"). '**' also covers `ship-batch/**`, the batch-landing opt-in.
|
|
46
|
+
#
|
|
47
|
+
# EDIT: on ONE self-hosted agent shared with trunk, go back to trunk-only until
|
|
48
|
+
# trunk has its own lane — branch runs queue ahead of the one trunk run a merge
|
|
49
|
+
# waits for (CONVENTIONS.md §7, "Self-hosted runners", #355). GitHub-hosted
|
|
50
|
+
# runners, a runner pool, or a trunk-only label picked in `runs-on` on
|
|
51
|
+
# github.ref all have that capacity; keep '**' there. Trunk-only means the
|
|
52
|
+
# branches this repo actually has — and never drop `dev` on a Tier A or C repo:
|
|
53
|
+
# dev is the trunk, so a main-only trigger runs zero checks on the branch you
|
|
54
|
+
# merge into, and nothing looks broken (CONVENTIONS.md §7).
|
|
55
|
+
branches: ['**']
|
|
56
|
+
pull_request:
|
|
57
|
+
# EDIT: keep only the branches this repo actually has (Tier A and C: dev is the
|
|
58
|
+
# trunk, main the release; Tier B: main only).
|
|
59
|
+
branches: [main, dev]
|
|
60
|
+
# A promotion pushed by the release workflow's token triggers no push run, so that workflow
|
|
61
|
+
# dispatches this one on main instead (templates/release-auto.yml, #440). Harmless elsewhere.
|
|
62
|
+
workflow_dispatch:
|
|
63
|
+
|
|
64
|
+
# One live run per branch: a new push cancels the superseded run on the same ref.
|
|
65
|
+
# Trunk is NEVER cancelled — every trunk sha keeps a completed run of its own, which
|
|
66
|
+
# is what the merge gate reads (CONVENTIONS.md §4, "Branch CI"). Pull-request runs
|
|
67
|
+
# group under refs/pull/<n>/merge, apart from the branch's push runs.
|
|
68
|
+
# EDIT: name exactly this repo's trunk (and release branch) here. A Tier C trunk
|
|
69
|
+
# may carry any name; one left off this list gets its trunk runs cancelled.
|
|
70
|
+
concurrency:
|
|
71
|
+
group: ci-${{ github.ref }}
|
|
72
|
+
cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.ref != 'refs/heads/dev' }}
|
|
73
|
+
|
|
74
|
+
env:
|
|
75
|
+
# EDIT: bump deliberately, not automatically.
|
|
76
|
+
GITLEAKS_VERSION: "8.30.1"
|
|
77
|
+
# EDIT: the importable package/directory to byte-compile. Often `src` or the app name.
|
|
78
|
+
PACKAGE_DIR: "."
|
|
79
|
+
|
|
80
|
+
# Self-hosted runner? The job layout below assumes GitHub-hosted capacity — a
|
|
81
|
+
# fresh machine per job. With few self-hosted agents every job is a queue slot,
|
|
82
|
+
# jobs from different runs interleave, and trunk can wait behind branch runs.
|
|
83
|
+
# Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
|
|
84
|
+
jobs:
|
|
85
|
+
gitleaks:
|
|
86
|
+
name: Secret scan (gitleaks)
|
|
87
|
+
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
88
|
+
steps:
|
|
89
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
90
|
+
with:
|
|
91
|
+
# Full history: gitleaks scans commits, not just the working tree, so a
|
|
92
|
+
# secret that was committed and later removed is still caught.
|
|
93
|
+
fetch-depth: 0
|
|
94
|
+
persist-credentials: false
|
|
95
|
+
|
|
96
|
+
- name: Install gitleaks (pinned release binary)
|
|
97
|
+
run: |
|
|
98
|
+
# Deliberately NOT gitleaks/gitleaks-action@v2: that action requires a paid
|
|
99
|
+
# GITLEAKS_LICENSE for repositories owned by an organization (free only for
|
|
100
|
+
# personal repos). The release binary itself is MIT and has no such gate.
|
|
101
|
+
# Repos also carry a local pre-commit gitleaks hook; this is the second layer.
|
|
102
|
+
# The asset is OS/arch-specific, so resolve both from uname instead of
|
|
103
|
+
# assuming the GitHub-hosted default: a hardcoded linux_x64 binary on a
|
|
104
|
+
# macOS self-hosted runner is an ELF the kernel cannot exec, and the step
|
|
105
|
+
# fails with exit 126 rather than anything mentioning the platform.
|
|
106
|
+
case "$(uname -s)" in
|
|
107
|
+
Darwin) os=darwin ;;
|
|
108
|
+
Linux) os=linux ;;
|
|
109
|
+
*) echo "unsupported OS: $(uname -s)" >&2; exit 1 ;;
|
|
110
|
+
esac
|
|
111
|
+
case "$(uname -m)" in
|
|
112
|
+
arm64|aarch64) arch=arm64 ;;
|
|
113
|
+
x86_64|amd64) arch=x64 ;;
|
|
114
|
+
*) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
|
|
115
|
+
esac
|
|
116
|
+
curl -sSL -o gitleaks.tar.gz \
|
|
117
|
+
"https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_${os}_${arch}.tar.gz"
|
|
118
|
+
# Into $RUNNER_TEMP, not /usr/local/bin: no sudo, no global write — the same
|
|
119
|
+
# step then works on BOTH GitHub-hosted and shared self-hosted runners
|
|
120
|
+
# (a shared runner is infrastructure; jobs must not mutate it).
|
|
121
|
+
tar -xzf gitleaks.tar.gz -C "$RUNNER_TEMP" gitleaks
|
|
122
|
+
chmod +x "$RUNNER_TEMP/gitleaks"
|
|
123
|
+
echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
|
|
124
|
+
rm -f gitleaks.tar.gz
|
|
125
|
+
|
|
126
|
+
- name: gitleaks detect
|
|
127
|
+
run: gitleaks detect --source . --no-banner
|
|
128
|
+
|
|
129
|
+
build:
|
|
130
|
+
name: Build (Python)
|
|
131
|
+
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
132
|
+
defaults:
|
|
133
|
+
run:
|
|
134
|
+
# EDIT: set to the directory holding the Python project if it is not at the root.
|
|
135
|
+
working-directory: .
|
|
136
|
+
steps:
|
|
137
|
+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
138
|
+
with:
|
|
139
|
+
persist-credentials: false
|
|
140
|
+
|
|
141
|
+
# ---------------------------------------------------------------------------
|
|
142
|
+
# Toolchain resolution. Precedence, highest first:
|
|
143
|
+
# 1. .github/project.yml -> python: <version>
|
|
144
|
+
# 2. .python-version (pyenv; also what most local tooling reads)
|
|
145
|
+
# 3. pyproject.toml -> [project] requires-python
|
|
146
|
+
# 4. FAIL.
|
|
147
|
+
#
|
|
148
|
+
# NOTE what is NOT on that list: requirements.txt. It pins DEPENDENCIES, never
|
|
149
|
+
# the interpreter — a repo with only a requirements.txt has declared nothing
|
|
150
|
+
# about which Python it runs on, and this workflow will (correctly) stop and
|
|
151
|
+
# say so. Add `python:` to project.yml or a `.python-version`; do not paper
|
|
152
|
+
# over it with a hardcoded version here.
|
|
153
|
+
#
|
|
154
|
+
# There is deliberately NO fallback default. A silent default is exactly how a
|
|
155
|
+
# repo here ended up building on Node 20 in CI while deploying on Node 22 —
|
|
156
|
+
# CI was green and proved nothing about what actually shipped. Python has the
|
|
157
|
+
# same failure with sharper edges: a minor is a real feature release, so 3.12
|
|
158
|
+
# vs 3.13 is not a cosmetic difference.
|
|
159
|
+
# ---------------------------------------------------------------------------
|
|
160
|
+
- name: Resolve Python version
|
|
161
|
+
id: toolchain
|
|
162
|
+
run: |
|
|
163
|
+
set -euo pipefail
|
|
164
|
+
|
|
165
|
+
# ">=3.13" / "~=3.12" / "3.13.1" / "3.13" -> "3.13" / "3.12" / "3.13.1"
|
|
166
|
+
normalise() {
|
|
167
|
+
printf '%s' "$1" \
|
|
168
|
+
| tr -d '"' \
|
|
169
|
+
| sed -E 's/^[^0-9]*//' \
|
|
170
|
+
| sed -E 's/[[:space:],].*$//' \
|
|
171
|
+
| sed -E 's/\.(x|\*)$//' \
|
|
172
|
+
| sed -E 's/[^0-9.].*$//' \
|
|
173
|
+
| sed -E 's/\.$//'
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
PY_VERSION=""
|
|
177
|
+
SOURCE=""
|
|
178
|
+
|
|
179
|
+
# 1. project.yml wins. Flat `python: 3.13` mapping; good enough, this file
|
|
180
|
+
# is a handful of keys by design.
|
|
181
|
+
if [ -f .github/project.yml ]; then
|
|
182
|
+
V="$(sed -nE 's/^[[:space:]]*python:[[:space:]]*"?([^"#[:space:]]+)"?.*/\1/p' .github/project.yml | head -1 || true)"
|
|
183
|
+
if [ -n "$V" ] && [ "$V" != "null" ]; then
|
|
184
|
+
PY_VERSION="$(normalise "$V")"; SOURCE=".github/project.yml (python:)"
|
|
185
|
+
fi
|
|
186
|
+
fi
|
|
187
|
+
|
|
188
|
+
# 2. .python-version
|
|
189
|
+
if [ -z "$PY_VERSION" ] && [ -f .python-version ]; then
|
|
190
|
+
V="$(grep -vE '^[[:space:]]*(#|$)' .python-version | head -1 | tr -d '[:space:]' || true)"
|
|
191
|
+
if [ -n "$V" ]; then
|
|
192
|
+
PY_VERSION="$(normalise "$V")"; SOURCE=".python-version"
|
|
193
|
+
fi
|
|
194
|
+
fi
|
|
195
|
+
|
|
196
|
+
# 3. pyproject.toml -> [project] requires-python. Read with a line match, not
|
|
197
|
+
# a TOML parser: the field is a single top-level string and the runner is
|
|
198
|
+
# not guaranteed to have tomllib available before setup-python has run.
|
|
199
|
+
if [ -z "$PY_VERSION" ] && [ -f pyproject.toml ]; then
|
|
200
|
+
V="$(sed -nE 's/^[[:space:]]*requires-python[[:space:]]*=[[:space:]]*["'"'"']([^"'"'"']+)["'"'"'].*/\1/p' pyproject.toml | head -1 || true)"
|
|
201
|
+
if [ -n "$V" ]; then
|
|
202
|
+
PY_VERSION="$(normalise "$V")"; SOURCE="pyproject.toml (requires-python)"
|
|
203
|
+
fi
|
|
204
|
+
fi
|
|
205
|
+
|
|
206
|
+
# 4. No declared source -> stop. Do not guess.
|
|
207
|
+
if [ -z "$PY_VERSION" ]; then
|
|
208
|
+
echo "::error::No Python version is declared in this repository, and this workflow refuses to guess one."
|
|
209
|
+
{
|
|
210
|
+
echo ""
|
|
211
|
+
echo "Declare it in ONE of these places (checked in this order):"
|
|
212
|
+
echo " 1. .github/project.yml -> python: \"3.13\" (preferred: one descriptor for the whole repo)"
|
|
213
|
+
echo " 2. .python-version -> 3.13 (also drives local dev via pyenv)"
|
|
214
|
+
echo " 3. pyproject.toml -> [project] requires-python = \">=3.13\""
|
|
215
|
+
echo ""
|
|
216
|
+
echo "requirements.txt does NOT count — it pins dependencies, not the interpreter."
|
|
217
|
+
echo "Pick the version your DEPLOY target runs. CI on a different minor than"
|
|
218
|
+
echo "production proves less than you think."
|
|
219
|
+
} >&2
|
|
220
|
+
exit 1
|
|
221
|
+
fi
|
|
222
|
+
|
|
223
|
+
echo "python-version=$PY_VERSION" >> "$GITHUB_OUTPUT"
|
|
224
|
+
echo "Python $PY_VERSION (resolved from: $SOURCE)"
|
|
225
|
+
echo "Python **$PY_VERSION** — resolved from \`$SOURCE\`" >> "$GITHUB_STEP_SUMMARY"
|
|
226
|
+
|
|
227
|
+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
|
|
228
|
+
with:
|
|
229
|
+
python-version: ${{ steps.toolchain.outputs.python-version }}
|
|
230
|
+
|
|
231
|
+
- name: Install dependencies
|
|
232
|
+
run: |
|
|
233
|
+
python -m pip install --upgrade pip
|
|
234
|
+
# Whichever manifest the repo actually has. A packaged project (pyproject)
|
|
235
|
+
# installs itself so imports resolve the way they will in production;
|
|
236
|
+
# a plain requirements.txt service just installs its pins.
|
|
237
|
+
if [ -f pyproject.toml ]; then
|
|
238
|
+
pip install -e .
|
|
239
|
+
elif [ -f requirements.txt ]; then
|
|
240
|
+
pip install -r requirements.txt
|
|
241
|
+
else
|
|
242
|
+
echo "::warning::No pyproject.toml or requirements.txt — nothing to install."
|
|
243
|
+
fi
|
|
244
|
+
|
|
245
|
+
- name: Byte-compile
|
|
246
|
+
# The cheapest gate there is: every module parses. Catches the syntax error
|
|
247
|
+
# that only ever runs on a code path nobody tests.
|
|
248
|
+
run: python -m compileall -q "$PACKAGE_DIR"
|
|
249
|
+
|
|
250
|
+
- name: Detect optional tooling
|
|
251
|
+
id: tools
|
|
252
|
+
run: |
|
|
253
|
+
# EDIT: add the tools this repo uses. Each is optional so a repo without it
|
|
254
|
+
# is not forced to adopt one to keep CI green.
|
|
255
|
+
# Because a tool missing here SKIPS its step and the job still concludes
|
|
256
|
+
# `success`, the files installed from above and here are part of the
|
|
257
|
+
# instrument: `colab ship`'s cure rule refuses a branch that changes them
|
|
258
|
+
# while trunk is red (CONVENTIONS.md §5, cure rule condition 6, #377). Installing
|
|
259
|
+
# from a file this template does not name (a lockfile, a new include)?
|
|
260
|
+
# Extend that rule's list, or accept that the cure rule cannot see it.
|
|
261
|
+
if [ -f requirements-dev.txt ]; then pip install -r requirements-dev.txt; fi
|
|
262
|
+
for t in ruff mypy pytest; do
|
|
263
|
+
if python -m "$t" --version >/dev/null 2>&1; then
|
|
264
|
+
echo "$t=true" >> "$GITHUB_OUTPUT"
|
|
265
|
+
else
|
|
266
|
+
echo "$t=false" >> "$GITHUB_OUTPUT"
|
|
267
|
+
echo "::notice::$t not installed — skipping."
|
|
268
|
+
fi
|
|
269
|
+
done
|
|
270
|
+
|
|
271
|
+
- name: Lint (ruff)
|
|
272
|
+
if: steps.tools.outputs.ruff == 'true'
|
|
273
|
+
run: python -m ruff check .
|
|
274
|
+
|
|
275
|
+
- name: Typecheck (mypy)
|
|
276
|
+
if: steps.tools.outputs.mypy == 'true'
|
|
277
|
+
run: python -m mypy "$PACKAGE_DIR"
|
|
278
|
+
|
|
279
|
+
- name: Test (pytest)
|
|
280
|
+
if: steps.tools.outputs.pytest == 'true'
|
|
281
|
+
run: python -m pytest -q
|