feat(ci): version-bump gate — the train's prod-hop version refusal, moved to PR time (backend#1563 Layer 1) - #172
Conversation
…PR time (backend#1563 L1) The release train already refuses to publish changed bytes under an already-released version (promote-repo.sh:version_preflight). Correct, and days late: backend#1561 spent a whole release leg discovering that py-package's pyproject.toml still said 0.17.0 while v0.17.0 was tagged and the delta touched tracebloc/*. This asks the same question on the PR that causes it. delta touches publish_paths AND v<version-on-this-PR> is already tagged -> red Not "the version file changed vs base", which #1563 words it as: that would demand a bump on every published-path PR, and one bump has always covered a whole release cycle. A check that is wrong on the common case gets removed. Parity is the point, so read_version and publishable_delta are copied from promote-repo.sh rule for rule — the per-extension anchors included, since those are what keep appVersion, a dependency pin and a leading comment out of the answer. Two deliberate divergences, both strictly tighter: `set -f` (a publish path is a glob, and promote-repo.sh only survives it by running where no publish path exists), and one paginated tag listing instead of a per-version git/ref probe that cannot tell 404 from 403. Fails closed on every unreadable input, and `soft-fail` does not reach any of them: it downgrades the verdict, never the machinery. Zero files scanned is a malfunction. No paths: filter and no job-level if:, so a required check can never go missing on a PR. 45-case decision table in scripts/tests/, run offline against a stubbed gh, covering every fail-closed path and all five repos' version file formats. Callers follow in one PR per repo, once this is on main.
Replayed against production, not just fixturesThe selftest proves the decision table; this proves the gate reads the real repos correctly. I extracted the The case this exists for — py-package #380 ( Red, on the PR, four days before the prod hop refused — naming the file to edit. That is the whole ticket. The passes, all correct, all on real deltas:
16 PRs, 15 green, 1 red, zero false positives — and every parser read the right number out of the right line of a real file: the bare Reproduce any row: python3 -c "import yaml;print(yaml.safe_load(open('.github/workflows/version-bump-gate.yml'))['jobs']['version-check']['steps'][0]['run'])" > /tmp/gate.sh
export GH_TOKEN=$(gh auth token) REPO_FULL=tracebloc/tracebloc-py-package \
VERSION_FILE=pyproject.toml PUBLISH_PATHS='tracebloc/* pyproject.toml' \
SOFT_FAIL=false LABELS='[]'
eval "$(gh pr view 380 --repo tracebloc/tracebloc-py-package \
--json baseRefOid,headRefOid,headRefName \
--jq '"export PR_BASE_SHA=\(.baseRefOid) PR_HEAD_SHA=\(.headRefOid) PR_HEAD_REF=\(.headRefName)"')"
bash /tmp/gate.sh(The |
…omotion exemption Self-review before Bugbot. The release-train exemption keyed on the head ref alone, and a head ref is chosen by whoever opens the PR: `release-train/anything` was an exemption anybody could mint, from a fork included. It only skipped a version check the train re-runs at the prod hop, so nothing could actually publish through it — but "the gate is disarmed by naming your branch" is not a property to leave in a gate. Now all three must hold, and the extra two are facts about a real promotion rather than claims made by its author: head ref prefix, head in THIS repository (never a fork), base in staging/main/master. A promotion never targets develop, so a PR that borrows the name to reach develop is evaluated normally — with a warning naming the mismatch, because a bypass that does not apply should be visible rather than silently absent. Also: an EMPTY version-file read is retried on purpose (it is the exact symptom of the Contents API lag that left py-package untagged on 2026-07-29), so the message after three failed attempts now names both possibilities instead of saying only "could not read". 50 cases, 4 of them new and all four red before this change.
…y 'not true' head.repo is absent on a PR from a deleted fork, so IS_FORK arrives empty and 'not true' read that as 'same repo' — granting the promotion exemption on a field nobody could read. Exempting on an unread field is the shape of every fail-open in backend#1409. Three-way now: false exempts, true says fork, anything else says the head repository could not be confirmed. Evaluating a genuine promotion by mistake costs a re-run; exempting a fork by mistake costs the gate.
Rollout signal, measured before anyone flips
|
| PR | verdict |
|---|---|
#77 feat/73-tooltip-controlled-click |
red — package.json still says 1.0.5, v1.0.5 released, src/components/atoms/Tooltip/Tooltip.css |
#71 chore/sync-develop-with-main |
red — same, src/components/atoms/Button/Button.css |
#67 feat/65-tooltip-portal-button-cta |
red — 1.0.2 released, src/components/atoms/Button/Button.css |
#63 fix/61-inline-input-icons |
red — 1.0.2 released, src/components/atoms/Input/Input.test.tsx |
These are true positives, not noise. design-system declares rc_tag: true, so tag_expected is true on its staging hop as well as prod — which is exactly the state repos.yml already documents: "a repo with rc_tag becomes un-hoppable the moment its version file equals its last final release, which is what design-system hit on the 2026-07-31 staging hop." Every one of those PRs was a contribution to that refusal. The gate is reporting a real, recurring condition at the moment it is created rather than at the hop.
Three things follow, and none of them changes the code in this PR:
- This is why
soft-faildefaults totrue. Arming this repo as a required check on day one would redden its normal flow before the team has adopted "bump with the change" — the exact way a linter gets removed instead of obeyed. The ladder in the header exists for this case; design-system is the repo that will need step 2 (watch the verdicts) to last longer than a day. - One question for
repos.yml, not for this gate.design-system'spublish_pathsissrc/*, andsrc/holds*.test.tsx. So a test-only change insidesrc/reads as publishable — fix(pii-gate): run under restrictive default token perms (contents-scoped Compare API) #63 is that case. The gate is faithfully reproducing the declaration rather than inventing a rule of its own, which is the whole design goal; if tests are not meant to be publishable, the fix belongs inrepos.ymlwhere both layers pick it up at once. Filing that separately rather than special-casing it here. - The other four repos are clean. py-package, cli, data-ingestors and client showed zero false positives across the sample in the comment above — the single red there is backend#1561's own PR.
I would still land the callers with the defaults (report-only) and let a week of verdicts decide when each repo flips.
|
Filed the |
Correction + the replay caveat, dated preciselyI widened the replay to the last 12 merged PRs in The caveat, which is a property of the gate and not a bug: the gate asks "is
Corrected totals over everything replayed (52 merged PRs across all five repos): 4 genuine reds, 3 replay artifacts, 45 green, 0 false positives. The genuine reds are backend#1561's own PR and three design-system PRs — the The |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit f64a263. Configure here.
…r match
Bugbot, .github#172. The yaml/toml/py branches take `head -1` on the LINE,
then run `grep -oE "$semver"` on it -- and grep -oE prints one line per match,
not per input line. A version line carrying a second semver in a trailing
comment
version = "1.2.3" # bumped from 1.0.0
therefore parses to the two-line value "1.2.3\n1.0.0". Measured, not
theorised.
Here that corrupts the regression guard: `sort -V | tail -1` answers 1.2.3
while `"$HEAD_VER"` is the whole two-line string, so the `!=` compare is true
and the gate refuses a perfectly legitimate bump. The bare-file branch already
guarded this with a trailing head -1; the other three did not.
The json branch is safe -- jq emits a single value and the pattern is anchored
with ^ -- so it is left alone rather than given a cosmetic head -1.
This same defect is in promote-repo.sh:read_version, which this file copies
rule for rule; it is fixed there in release-train#40. In the train the
consequence is worse than a false refusal: the parsed value is interpolated
into the tag-probe URL, a malformed URL 404s, and the caller reads that as
"this version is not released" -- fail-OPEN on the one check that stops a
re-publish under an existing tag.
|
Fixed in Confirmed by measurement, exactly as described — Here that corrupts the regression guard: The same defect is in Fixed there in release-train#41 with three regression cases (one per branch, since they are three independent greps). Mutation-checked: 465 pass with the fix; revert the fix and keep the tests and exactly those 3 fail. Both copies now carry the identical parse, which is the parity property this gate is built on. Good catch — it survived review here precisely because it was faithful to the source. |
2 participants
Summary
Layer 1 of tracebloc/backend#1563: the release train's version refusal, moved from the prod hop to the PR that causes it.
The train already enforces this.
release-train scripts/promote-repo.sh:version_preflightfails a hop withbecause publishing would put different bytes under a version that has already shipped. Correct, and days late. On 2026-08-05 that refusal cost a whole release leg plus a hand diagnosis (backend#1561 → tracebloc-py-package#389):
pyproject.tomlsaid0.17.0,v0.17.0was tagged since 2026-08-03, and the staging↔master delta touched 8 files undertracebloc/*. Nobody found out until the hop, and the person who found out was not the person who wrote it.This PR adds the reusable workflow that asks the same question on the PR. No callers yet — one follow-up PR per repo (each targeting
develop) once this is onmain, since callers pin@main.What I measured, not assumed
Parsed out of
repos.ymlontracebloc/release-train@main(2026-08-06). Five repos declare aversion_file, matching the ticket's list:version_filepublish_pathsrc_tagtracebloc-py-packagepyproject.tomltracebloc/* pyproject.tomlcliVERSIONcmd/* internal/* go.mod go.sum VERSIONdesign-systempackage.jsonsrc/*data-ingestorstracebloc_ingestor/__init__.pytracebloc_ingestor/*clientclient/Chart.yamlclient/*Every other train repo (
backend,tracebloc-engine,client-runtime,averaging-service,frontend-app,tracebloc-website,model-zoo,start-training,.github,docs,e2e-test-agent) declares noversion_fileand is out of scope for this gate.How the parsing matches
promote-repo.shread_version's case table, copied rule for rule — the anchors are the load-bearing part, and each covers a real trap:*.jsonjq '.version', then^X.Y.Z(-pre)?*.yaml/*.yml^version:appVersion:out of the answer*.toml^version *= *"*.py^__version__ *= *["']SCHEMA_VERSIONconstant is not the package version^X.Y.Zat the start of a lineSame semver regex, prerelease suffix preserved the same way.
publishable_deltais copied too: space-separated globs, matched with shellcaseagainst both.filenameand.previous_filename(a file renamed out of a published tree left the package, and GitHub reports only its new path), one line per file so the 300-file cap counts files rather than paths, and the same yes / no / cannot-tell trichotomy where cannot-tell is treated exactly like yes (backend#1439).scripts/tests/version-bump-gate-selftest.shasserts all five formats against their real shapes, including the traps above. That test is the parity claim; without it "same rules" is an assertion in a comment.Two deliberate divergences, both strictly tighter
set -f.for pat in $PUBLISH_PATHSis a glob context — bash expandscmd/*against$PWDbefore the loop body sees it.promote-repo.shis saved only by running from a checkout where no publish path happens to exist. A coincidence of the working directory is not a property, and the selftest has a case that runs the gate from a directory containing a matching tree.matching-refs/tags/vread instead of a per-versiongit/ref/tags/v$verprobe. That probe collapses 404 (not released) and 403 / rate limit (could not tell) into the same falsy result — it fail-opens on a bad day. One listing either reads or it does not, and it feeds the regression guard too, so both questions come from the same bytes. (Measured:git/ref/tags/v0.10onclireturns a clean 404, so the endpoint is exact-match — the divergence is about error handling, never about the answer.)The one place I did not implement the ticket literally
backend#1563 words Layer 1 as "fails when published paths change but the version file is unchanged vs base". Implemented literally, that demands a bump on every published-path PR — and the train has never asked for that. One bump covers a whole release cycle: the first PR after a release must bump, and every later one legitimately rides the already-bumped, still-unreleased version. Reddening all of those measures the wrong thing, and a check that is wrong on the common case gets removed rather than obeyed (
code-quality.yml's soft-fail note is the same lesson).So the enforced rule is
version_preflight's, verbatim:Red for exactly the case #1561 hit, green for exactly the cases the train promotes. Flag it if you want the literal reading instead — it is a small change, but I think it would make the check hated.
Behaviour on each edge case
Fails (verdict —
soft-failapplies):<file>in this PR", naming the matched file and the glob it matchedlatest_final's regression guard;v$veris free but GitHub'slatestand the installer bootstrap would still point at the higher tagFails (malfunction —
soft-failnever applies): missingversion-file/publish-pathsinput; missing base/head SHA; unreadable compare; compare with no merge base; empty file list (zero files scanned is a malfunction, not a pass — GitHub omits the list on very large compares, so empty is indistinguishable from "changed nothing"); version file unreadable or unparseable on head; unreadable or unparseable at the merge base; unreadable tag listing;grepexiting >1 while searching it; 300 files with no match (the API's page cap has no truncation flag, so "nothing published changed" cannot be asserted — note the asymmetry: a match is sound on a truncated list, so a large compare that does match still gets a precise answer).soft-faildowngrades the verdict, never the machinery. A gate that cannot evaluate is broken, and broken must look different from clean in both modes — backend#1409's entire finding was six repos carrying a green check that had never compared anything. Three selftest cases assert exactly this.Passes (each with a stated reason, never a silent one):
docs-only / CI-only / test-only — the delta matches no publish path, so nothing this repo ships changed. Green even with the version stale and already released: that is precisely the no-publishable-delta no-op the train grew in backend#1439, and refusing here would leave such a PR with no green path at all. The message names the file count and the globs it scanned against, so a green check is auditable rather than merely quiet. This is the case the
clicomment inrepos.ymldescribes — the 2026-08-04 staging hop refused on two CI-only pin PRs.the PR bumps to an unreleased version
the PR changes published files but the base already carries an unreleased bump ("no bump is owed")
the PR introduces the version file (absent at the merge base is a definite answer, not a read failure)
release-train promotion PRs — head
release-train/*orhotfix-backmerge/*, from this repository, intostaging/main/master. Evaluated and green with a reason, not skipped. Not a courtesy: the train scopes its preflight per hop viatag_expected, and py-package and data-ingestors declare norc_tag, so theirdevelop → staginghop deliberately runs no version preflight. Gating that PR here would block a promotion the train is entitled to make — the exact disagreement this file exists to avoid. The cargo PRs were each gated on their way intodevelop.All three conditions are checked because a branch name is not a credential (tightened in
be406be/f64a263after self-review). A head ref is chosen by whoever opens the PR, sorelease-train/anythingalone is an exemption anybody could mint, from a fork included. The base branch and the head repository are properties of a real promotion rather than claims made by its author, and a promotion never targetsdevelop. The fork test demands a confirmedfalse, not merely "nottrue" —head.repois absent on a PR from a deleted fork, and an exemption granted on a field nobody could read is the same fail-open shape as backend#1409. A PR that merely borrows the name is evaluated normally, with a warning naming the mismatch: a bypass that does not apply should be visible, not silently absent.Override:
skip-version-gatelabel, checked first, ahead of every refusal.public-pii-gate.ymlshipped its override below the refusals, so on exactly the PRs that needed rescuing the refusal exited first. It buys a merge, not a release — the train still refuses at the prod hop.House rules
if:— a skipped required check leaves PRs pending forever.paths:filter on the caller and none here. All the path judgment happens inside the job, where "not applicable" is a green result with a reason rather than an absent one.actions/checkoutandactions/setup-python, both pinned to full commit SHAs (D10).contents: readonly, so callers pass nosecrets:line (RFC-BACKEND-1405 Q5).soft-faildefaults true — migration setting, with the four-step ladder torequiredin the header. Same shape ascode-quality.yml.run:block, so every attacker-controlled value (branch name, label names) arrives as an environment variable rather than spliced into script text — and so the selftest can extract and execute it. If a future edit interpolates${{ }}into the body, the selftest fails loudly rather than silently covering less.Config source, and the drift it implies — stated plainly
version_fileandpublish_pathslive in release-train'srepos.yml, which is the authority. This workflow cannot read it:release-trainis private, and a reusable called from another repo runs with that repo'sGITHUB_TOKEN. Handing five repos a cross-repo PAT to run a PR check costs more than the drift it would close, so the caller declares the values and the job echoes both into the summary on every run, where a wrong one is visible rather than silent. Keeping them in step is a two-file edit, exactly likerepos.ymlvsrepo-inventory.yml'srelease_trainflag.Test
51 cases against a stubbed
gh: the #1561 shape, every legitimate pass, every fail-closed path, the soft-fail/machinery split, the override's ordering and its exact-match requirement, rename-out-of-tree, glob safety under a hostile$PWD, and all five repos' version file formats with their wrong-line traps.actionlint -shellcheckandshellcheckare clean;house-rules.shreports no findings.Follow-ups (not in this PR)
develop, after this reachesmain: py-package, cli, design-system, data-ingestors, client.repo-inventory.ymlgainsversion-bump-gate.ymlunderreusables:with an entry per repo in the caller PRs, not here — the inventory header's own rule is "land the caller first, flip the entry after", and arequiredentry added before any caller exists fails the drift guard on day one.Closes nothing — backend#1563 stays open for Layer 2.
Refs backend#1563, backend#1561, backend#1439, backend#1427, backend#1409.
Note
Medium Risk
The gate will block merges once callers enable it and turn off soft-fail; incorrect
version-file/publish-pathsor parity drift from the train could false-positive or false-negative on release-critical PRs.Overview
Adds a reusable
workflow_callPR gate that mirrors release-trainversion_preflight: fail when the PR diff touches publish paths and the version read from the caller’sversion-fileis already tagged. The job usesghonly (no checkout actions), parses versions the same way aspromote-repo.sh, matches publish globs including renames, fail-closes on API/parse ambiguity, defaultssoft-fail: true, honorsskip-version-gatefirst, and auto-passes vetted release-train / hotfix-backmerge promotions.Testing & adoption: New
scripts/tests/version-bump-gate-selftest.shextracts the gate’s env-drivenrun:block and runs 51 cases against a stubbedgh;version-bump-gate-selftest.ymlruns that on changes to the gate. README tells repos with aversion_fileinrepos.ymlto add a thin caller (not included here).Reviewed by Cursor Bugbot for commit 99e9206. Bugbot is set up for automated code reviews on this repo. Configure here.