@futurelastic/colab-handbook 1.12.0-rc.14 → 1.12.0-rc.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/templates/README.md +19 -0
- package/templates/ci-laravel.yml +57 -0
- package/templates/ci-node.yml +53 -0
- package/templates/ci-python.yml +53 -0
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -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
|
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:
|
|
@@ -376,6 +429,10 @@ jobs:
|
|
|
376
429
|
migrations:
|
|
377
430
|
name: Migration round-trip (${{ matrix.engine }})
|
|
378
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' }}
|
|
379
436
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
380
437
|
strategy:
|
|
381
438
|
fail-fast: false
|
package/templates/ci-node.yml
CHANGED
|
@@ -69,8 +69,59 @@ env:
|
|
|
69
69
|
# jobs from different runs interleave, and trunk can wait behind branch runs.
|
|
70
70
|
# Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
|
|
71
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
|
+
|
|
72
121
|
gitleaks:
|
|
73
122
|
name: Secret scan (gitleaks)
|
|
123
|
+
needs: dedupe
|
|
124
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
74
125
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
75
126
|
steps:
|
|
76
127
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
@@ -115,6 +166,8 @@ jobs:
|
|
|
115
166
|
|
|
116
167
|
build:
|
|
117
168
|
name: Build
|
|
169
|
+
needs: dedupe
|
|
170
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
118
171
|
# A repo can adopt this template before it has any application code at all —
|
|
119
172
|
# a fresh Tier B scaffold with decisions locked and a backlog filed, nothing
|
|
120
173
|
# else. Unguarded, every step below still runs: "Install dependencies" warns
|
package/templates/ci-python.yml
CHANGED
|
@@ -83,8 +83,59 @@ env:
|
|
|
83
83
|
# jobs from different runs interleave, and trunk can wait behind branch runs.
|
|
84
84
|
# Read CONVENTIONS.md §7, "Self-hosted runners", before choosing a label.
|
|
85
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
|
+
|
|
86
135
|
gitleaks:
|
|
87
136
|
name: Secret scan (gitleaks)
|
|
137
|
+
needs: dedupe
|
|
138
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
88
139
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
89
140
|
steps:
|
|
90
141
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
|
|
@@ -129,6 +180,8 @@ jobs:
|
|
|
129
180
|
|
|
130
181
|
build:
|
|
131
182
|
name: Build (Python)
|
|
183
|
+
needs: dedupe
|
|
184
|
+
if: ${{ !cancelled() && needs.dedupe.outputs.tested != 'true' }}
|
|
132
185
|
runs-on: ubuntu-latest # EDIT: self-hosted label if this repo needs one.
|
|
133
186
|
defaults:
|
|
134
187
|
run:
|