Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-9619 Hold stable publication of a release carrying the flip (#6781)

Andrew Mikofalvyda2b51e90c4c
diff --git a/.github/scripts/bug-lane.mjs b/.github/scripts/bug-lane.mjs
index ab284ec95..449bbc050 100644
--- a/.github/scripts/bug-lane.mjs
+++ b/.github/scripts/bug-lane.mjs
@@ -9,6 +9,7 @@ import {
withBumpVerdicts,
} from '../../scripts/compute-stable-version.mjs';
import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';
+import { describeHold, evaluatePick, gitReader, SHALLOW_BOUNDARY } from './release-hold.mjs';
import { makeResolveChangesetPrUrl, makeResolveIssuesForUrl } from './select-beta-to-promote.mjs';
import {
createShippedFixCheck,
@@ -137,10 +138,36 @@ export function holdBugLaneBatch({ stable, check }) {
return `${refusalHeadline(verdict, stable)} point-release.yml refuses a point release over ${stable} unless its batch also carries those fixes.`;
}
-export function ticketsByRef(result) {
+export function screenPicksForReleaseHold({ fixRefs, evaluate }) {
+ const admitted = [];
+ const log = [];
+ for (const ref of fixRefs) {
+ let verdict;
+ try {
+ verdict = evaluate(ref);
+ } catch (err) {
+ if (err?.code !== SHALLOW_BOUNDARY) {
+ throw new Error(`the release-hold check failed on ${ref}, so this tick hands nothing to verify: ${err.message}`, {
+ cause: err,
+ });
+ }
+ log.push(`::warning::bug-lane: holding ${ref} this tick, because the release-hold check could not decide: ${err.message}`);
+ continue;
+ }
+ if (verdict.held) {
+ log.push(`::warning::bug-lane: holding ${ref}: ${describeHold(verdict)}`);
+ continue;
+ }
+ log.push(`bug-lane: ${describeHold(verdict)}`);
+ admitted.push(ref);
+ }
+ return { fixRefs: admitted, log };
+}
+
+export function ticketsByRef(result, refs = result.fixRefs) {
const out = {};
for (const c of result.perCommit) {
- if (c.qualifies && c.linkedIssues.length > 0) out[c.sha] = [...c.linkedIssues];
+ if (c.qualifies && refs.includes(c.sha) && c.linkedIssues.length > 0) out[c.sha] = [...c.linkedIssues];
}
return out;
}
@@ -247,11 +274,18 @@ async function main() {
: `::notice::bug-lane: no qualifying fixes this tick (${result.reason}).`,
);
- const held =
- result.fixRefs.length > 0 ? holdBugLaneBatch({ stable, check: createShippedFixCheck() }) : null;
+ const holdGit = gitReader();
+ const screened = screenPicksForReleaseHold({
+ fixRefs: result.fixRefs,
+ evaluate: (ref) => evaluatePick({ candidate: ref, git: holdGit }),
+ });
+ for (const line of screened.log) console.log(line);
+ const fixRefs = screened.fixRefs;
+
+ const held = fixRefs.length > 0 ? holdBugLaneBatch({ stable, check: createShippedFixCheck() }) : null;
if (held !== null) {
console.log(
- `::notice::bug-lane: holding ${result.fixRefs.length} qualifying fix(es) this tick, so no point release is attempted. ${held}`,
+ `::notice::bug-lane: holding ${fixRefs.length} qualifying fix(es) this tick, so no point release is attempted. ${held}`,
);
}
@@ -259,9 +293,9 @@ async function main() {
appendFileSync(
process.env.GITHUB_OUTPUT,
[
- `fix_refs=${held === null ? result.fixRefs.join(',') : ''}`,
+ `fix_refs=${held === null ? fixRefs.join(',') : ''}`,
`stable=${stable}`,
- `fix_tickets=${held === null ? JSON.stringify(ticketsByRef(result)) : '{}'}`,
+ `fix_tickets=${held === null ? JSON.stringify(ticketsByRef(result, fixRefs)) : '{}'}`,
'',
].join('\n'),
);
diff --git a/.github/scripts/bug-lane.test.mjs b/.github/scripts/bug-lane.test.mjs
index c52f8cd18..96df60af5 100644
--- a/.github/scripts/bug-lane.test.mjs
+++ b/.github/scripts/bug-lane.test.mjs
@@ -6,8 +6,16 @@ import { fileURLToPath } from 'node:url';
import { afterAll, afterEach, beforeAll, describe, expect, test } from 'vitest';
import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';
import { configureTestGitRepository } from '../../test-support/configure-git-fixture.test-helper.ts';
-import { evaluateBugLane, holdBugLaneBatch, makeIsInStable, readPendingBumps } from './bug-lane.mjs';
+import {
+ evaluateBugLane,
+ holdBugLaneBatch,
+ makeIsInStable,
+ readPendingBumps,
+ screenPicksForReleaseHold,
+ ticketsByRef,
+} from './bug-lane.mjs';
import { expectNoAutomaticGitMaintenance } from './git-fixture-maintenance.test-helper.mjs';
+import { RELEASE_HOLD_SENTINEL, SHALLOW_BOUNDARY } from './release-hold.mjs';
const FIX_A = 'a'.repeat(40);
const FIX_B = 'b'.repeat(40);
@@ -183,6 +191,67 @@ describe('holdBugLaneBatch (no batch a point release would refuse)', () => {
});
});
+describe('screenPicksForReleaseHold (no pick that brings the release hold)', () => {
+ const verdict = (sha, held) => ({ kind: 'pick', candidate: sha, sha: sha.padEnd(40, '0'), firstParent: 'f'.repeat(40), path: RELEASE_HOLD_SENTINEL, held });
+
+ test('keeps a pick that does not add the sentinel and says so', () => {
+ const screened = screenPicksForReleaseHold({ fixRefs: ['aaa'], evaluate: (ref) => verdict(ref, false) });
+ expect(screened.fixRefs).toEqual(['aaa']);
+ expect(screened.log).toEqual([
+ `bug-lane: aaa (aaa000000000) does not add ${RELEASE_HOLD_SENTINEL} against its first parent ffffffffffff, so the release hold does not apply.`,
+ ]);
+ });
+
+ test('drops a pick that adds the sentinel, and one it cannot read, and keeps the rest', () => {
+ const screened = screenPicksForReleaseHold({
+ fixRefs: ['flip', 'clean', 'shallow'],
+ evaluate: (ref) => {
+ if (ref === 'shallow') {
+ throw Object.assign(new Error('names first parent 123, which is not in this clone, as at a shallow boundary'), {
+ code: SHALLOW_BOUNDARY,
+ });
+ }
+ return verdict(ref, ref === 'flip');
+ },
+ });
+ expect(screened.fixRefs).toEqual(['clean']);
+ expect(screened.log[0]).toMatch(/^::warning::bug-lane: holding flip: flip \(flip00000000\) adds /);
+ expect(screened.log[2]).toBe(
+ '::warning::bug-lane: holding shallow this tick, because the release-hold check could not decide: names first parent 123, which is not in this clone, as at a shallow boundary',
+ );
+ });
+
+ test('fails the tick when the check breaks for any other reason, rather than holding every pick quietly', () => {
+ const broken = new Error('git cat-file failed (exit 128): fatal: not a git repository');
+ expect(() =>
+ screenPicksForReleaseHold({
+ fixRefs: ['clean', 'other'],
+ evaluate: (ref) => {
+ if (ref === 'other') throw broken;
+ return verdict(ref, false);
+ },
+ }),
+ ).toThrow(
+ expect.objectContaining({
+ cause: broken,
+ message: `the release-hold check failed on other, so this tick hands nothing to verify: ${broken.message}`,
+ }),
+ );
+ });
+
+ test('ticketsByRef lists only the refs that are handed over', () => {
+ const result = {
+ fixRefs: ['a', 'b'],
+ perCommit: [
+ { sha: 'a', qualifies: true, linkedIssues: ['PRD-1'] },
+ { sha: 'b', qualifies: true, linkedIssues: ['PRD-2'] },
+ ],
+ };
+ expect(ticketsByRef(result)).toEqual({ a: ['PRD-1'], b: ['PRD-2'] });
+ expect(ticketsByRef(result, ['b'])).toEqual({ b: ['PRD-2'] });
+ });
+});
+
describe('makeIsInStable', () => {
let dir;
let fixOnMain;
@@ -300,6 +369,7 @@ describe('the bug-lane entry points the two jobs run', () => {
const OK_ROOT = join(dirname(SCRIPT), '..', '..');
const COPIED = [
'.github/scripts/bug-lane.mjs',
+ '.github/scripts/release-hold.mjs',
'.github/scripts/select-beta-to-promote.mjs',
'.github/scripts/shipped-fix-containment.mjs',
'scripts/compute-stable-version.mjs',
@@ -491,4 +561,72 @@ describe('the bug-lane entry points the two jobs run', () => {
'::notice::bug-lane: holding 1 qualifying fix(es) this tick, so no point release is attempted. The newest stable tag v1.0.0 has no published Release',
);
});
+
+ const runWithBugLinks = (root) => {
+ const verdicts = run(SCRIPT, root, { args: ['--read-bumps'] }).output.trim().slice('bump_verdicts='.length);
+ const linear = linearStub();
+ return run(isolatedScript(), root, {
+ env: { LINEAR_API_KEY: 'placeholder-linear-key', LINEAR_CALLS: linear.calls, BUMP_VERDICTS: verdicts },
+ preload: linear.preload,
+ });
+ };
+
+ test('hands over a fix that does not add the release hold, and says the hold does not apply', () => {
+ const { root, fix } = pendingRepo();
+ const res = runWithBugLinks(root);
+ expect(res.status, res.stderr).toBe(0);
+ expect(res.output).toBe(`fix_refs=${fix}\nstable=v1.0.0\nfix_tickets={"${fix}":["PRD-1"]}\n`);
+ expect(res.stdout).toContain(
+ `bug-lane: ${fix} (${fix.slice(0, 12)}) does not add ${RELEASE_HOLD_SENTINEL} against its first parent`,
+ );
+ });
+
+ test('leaves out a fix whose own commit adds the release hold, and hands over the post-flip fix after it', () => {
+ const { root, fix } = pendingRepo();
+ mkdirSync(join(root, '.github', 'release-holds'), { recursive: true });
+ writeFileSync(join(root, RELEASE_HOLD_SENTINEL), 'held\n');
+ writeFileSync(join(root, '.changeset', 'flip.md'), '---\n"@inkeep/open-knowledge": patch\n---\n\nflip\n');
+ git(root, 'add', '-A');
+ git(root, 'commit', '-q', '-m', 'fix: the commit that brings the hold (#103)');
+ const flip = git(root, 'rev-parse', 'HEAD');
+ writeFileSync(join(root, '.changeset', 'after.md'), '---\n"@inkeep/open-knowledge": patch\n---\n\nafter\n');
+ git(root, 'add', '-A');
+ git(root, 'commit', '-q', '-m', 'fix: a post-flip fix (#104)');
+ const after = git(root, 'rev-parse', 'HEAD');
+ const res = runWithBugLinks(root);
+ expect(res.status, res.stderr).toBe(0);
+ const outputs = Object.fromEntries(res.output.trim().split('\n').map((line) => line.split(/=(.*)/s).slice(0, 2)));
+ expect(outputs.fix_refs.split(',').sort()).toEqual([fix, after].sort());
+ expect(outputs.stable).toBe('v1.0.0');
+ expect(JSON.parse(outputs.fix_tickets)).toEqual({ [fix]: ['PRD-1'], [after]: ['PRD-1'] });
+ expect(res.stdout).toContain(`::warning::bug-lane: holding ${flip}: ${flip} (${flip.slice(0, 12)}) adds ${RELEASE_HOLD_SENTINEL}`);
+ });
+
+ test('holds a pick at a shallow boundary, whose first parent is not in the clone', () => {
+ const origin = scratch('bug-lane-shallow-origin-');
+ git(origin, 'init', '-q', '-b', 'main');
+ configureTestGitRepository(origin, (args) => git(origin, ...args));
+ writeFileSync(join(origin, 'README.md'), 'stable\n');
+ git(origin, 'add', '-A');
+ git(origin, 'commit', '-q', '-m', 'stable');
+ git(origin, 'tag', 'v1.0.0');
+ writeFileSync(join(origin, 'notes.txt'), 'between\n');
+ git(origin, 'add', '-A');
+ git(origin, 'commit', '-q', '-m', 'chore: between the stable and the fix');
+ mkdirSync(join(origin, '.changeset'), { recursive: true });
+ writeFileSync(join(origin, '.changeset', 'fix-crash.md'), '---\n"@inkeep/open-knowledge": patch\n---\n\nfix\n');
+ git(origin, 'add', '-A');
+ git(origin, 'commit', '-q', '-m', 'fix: stop the crash (#101)');
+ const fix = git(origin, 'rev-parse', 'HEAD');
+ const clone = scratch('bug-lane-shallow-');
+ git(clone, 'init', '-q', '-b', 'main');
+ configureTestGitRepository(clone, (args) => git(clone, ...args));
+ git(clone, 'fetch', '-q', '--depth', '1', `file://${origin}`, 'refs/heads/main:refs/remotes/origin/main', 'refs/tags/v1.0.0:refs/tags/v1.0.0');
+ git(clone, 'switch', '-q', '-C', 'main', 'origin/main');
+ const res = runWithBugLinks(clone);
+ expect(res.status, res.stderr).toBe(0);
+ expect(res.output).toBe('fix_refs=\nstable=v1.0.0\nfix_tickets={}\n');
+ expect(res.stdout).toContain(`::warning::bug-lane: holding ${fix} this tick, because the release-hold check could not decide:`);
+ expect(res.stdout).toContain('as at a shallow boundary');
+ });
});
diff --git a/.github/scripts/point-release-plan.mjs b/.github/scripts/point-release-plan.mjs
index b57159096..071d6e26d 100644
--- a/.github/scripts/point-release-plan.mjs
+++ b/.github/scripts/point-release-plan.mjs
@@ -19,6 +19,7 @@ import {
stableNotes,
withNoteLevels,
} from '../../scripts/render-stable-notes.mjs';
+import { describeHold, evaluateTree, gitReader } from './release-hold.mjs';
import {
describeNoSelection,
listPrebuildRuns,
@@ -315,6 +316,15 @@ export function guardShipsPublishedFixes({ verdict, latestStableTag }) {
);
}
+export function guardReleaseHold({ verdict, latestStableTag }) {
+ const label = `${latestStableTag} plus the applied fixes`;
+ if (!verdict.held) return pass(describeHold(verdict, label));
+ return refuse(
+ 'release-hold',
+ `${describeHold(verdict, label)} A pick brought the hold onto the stable: leave that ref out of fix_refs.`,
+ );
+}
+
export function guardRefsOnMain({ fixRefs, isOnMain }) {
const offenders = fixRefs.filter((ref) => !isOnMain(ref));
if (offenders.length > 0) {
@@ -521,6 +531,7 @@ export function runPointRelease(opts, io) {
selection: io.gh.selectNativeConfigPrebuild(syntheticSha),
}),
);
+ checkGuard(guards, guardReleaseHold({ verdict: io.hold.evaluate(syntheticSha), latestStableTag }));
checkGuard(
guards,
guardShipsPublishedFixes({ verdict: io.containment.evaluate(syntheticSha), latestStableTag }),
@@ -741,6 +752,9 @@ export function formatReleaseNotes(plan) {
export function realIo() {
return {
containment: createShippedFixCheck(),
+ hold: {
+ evaluate: (sha) => evaluateTree({ candidate: sha, git: gitReader() }),
+ },
fs: {
readWorktreeFile: (path) => readFileSync(path, 'utf8'),
writeWorktreeFile: (path, content) => writeFileSync(path, content),
diff --git a/.github/scripts/point-release-plan.test.mjs b/.github/scripts/point-release-plan.test.mjs
index b774bac91..92a52f07e 100644
--- a/.github/scripts/point-release-plan.test.mjs
+++ b/.github/scripts/point-release-plan.test.mjs
@@ -19,6 +19,7 @@ import {
guardNativeConfigProvenance,
guardPatchOnly,
guardRefsOnMain,
+ guardReleaseHold,
guardResolvePathsAllowlisted,
guardShipsPublishedFixes,
guardTagFree,
@@ -32,6 +33,7 @@ import {
runPointRelease,
verifyWorkspaceMatchesLockfile,
} from './point-release-plan.mjs';
+import { RELEASE_HOLD_SENTINEL } from './release-hold.mjs';
import { appliedOrigins } from './shipped-fix-containment.mjs';
function inspectGitEscapes(source) {
@@ -89,6 +91,14 @@ const containedVerdict = (candidateSha = 'synthetic-sha') => ({
uncovered: [],
});
+const unheldVerdict = (sha) => ({
+ kind: 'tree',
+ candidate: sha,
+ sha,
+ path: RELEASE_HOLD_SENTINEL,
+ held: false,
+});
+
const droppedFixVerdict = () => ({
...containedVerdict(),
ok: false,
@@ -579,10 +589,12 @@ function makeIo(overrides = {}) {
worktree = {},
publishedTags = [stableTag],
containmentVerdict = containedVerdict,
+ holdVerdict = unheldVerdict,
} = overrides;
const calls = { tag: 0, pushTag: 0, createRelease: 0, dispatch: 0 };
const evaluated = [];
+ const holdEvaluated = [];
const dispatches = [];
const releases = [];
const applied = [];
@@ -604,6 +616,13 @@ function makeIo(overrides = {}) {
reads,
worktree,
evaluated,
+ holdEvaluated,
+ hold: {
+ evaluate: (sha) => {
+ holdEvaluated.push(sha);
+ return holdVerdict(sha);
+ },
+ },
containment: {
publishedStableTags: () =>
typeof publishedTags === 'function' ? publishedTags() : [...publishedTags],
@@ -1270,6 +1289,58 @@ describe('runPointRelease keeps every fix a published stable shipped', () => {
});
});
+describe('runPointRelease refuses a synthetic commit that carries the release hold', () => {
+ const heldVerdict = (sha) => ({ ...unheldVerdict(sha), held: true });
+
+ test('reads the synthetic commit, not the base, and records in the guard trail that the hold does not apply', () => {
+ const io = makeIo();
+ const plan = runPointRelease({ mode: 'revert', fixRefs: ['bad1'], dryRun: true }, io);
+ expect(io.holdEvaluated).toEqual(['synthetic-sha']);
+ expect(plan.guards.map((g) => g.message)).toContain(
+ `v0.32.0 plus the applied fixes (synthetic-sh) does not carry ${RELEASE_HOLD_SENTINEL}, so the release hold does not apply.`,
+ );
+ });
+
+ test('refuses with release-hold and touches nothing remote, even in a real run', () => {
+ const io = makeIo({ holdVerdict: heldVerdict });
+ let refusal;
+ try {
+ runPointRelease({ mode: 'revert', fixRefs: ['bad1'], dryRun: false }, io);
+ } catch (err) {
+ refusal = err;
+ }
+ expect(refusal?.code).toBe('release-hold');
+ expect(refusal?.message).toContain(`v0.32.0 plus the applied fixes (synthetic-sh) carries ${RELEASE_HOLD_SENTINEL}`);
+ expect(refusal?.message).toContain('leave that ref out of fix_refs');
+ expect(io.calls).toEqual({ tag: 0, pushTag: 0, createRelease: 0, dispatch: 0 });
+ });
+
+ test('a hold it cannot read fails the run before anything is tagged', () => {
+ const io = makeIo({
+ holdVerdict: () => {
+ throw new Error('git ls-tree failed (exit 128): fatal: not a tree object');
+ },
+ });
+ let thrown;
+ try {
+ runPointRelease({ mode: 'revert', fixRefs: ['bad1'], dryRun: false }, io);
+ } catch (err) {
+ thrown = err;
+ }
+ expect(thrown?.message).toMatch(/not a tree object/);
+ expect(thrown?.code).toBeUndefined();
+ expect(io.calls).toEqual({ tag: 0, pushTag: 0, createRelease: 0, dispatch: 0 });
+ });
+
+ test('guardReleaseHold passes an unheld verdict and refuses a held one', () => {
+ expect(guardReleaseHold({ verdict: unheldVerdict('abc'), latestStableTag: 'v1.0.0' }).ok).toBe(true);
+ expect(guardReleaseHold({ verdict: { ...unheldVerdict('abc'), held: true }, latestStableTag: 'v1.0.0' })).toMatchObject({
+ ok: false,
+ code: 'release-hold',
+ });
+ });
+});
+
describe('runPointRelease with an authorized config path', () => {
const authorized = ['pnpm-workspace.yaml'];
@@ -2032,6 +2103,38 @@ describe('the production entry points the release workflows run', () => {
expect(res.stdout).toMatch(/::warning::.*without the notes-source marker/);
});
+ test.each([
+ ['a post-flip fix', 'post-flip-fix.txt', false],
+ ['the flip itself', RELEASE_HOLD_SENTINEL, true],
+ ])('realIo reads the synthetic tree of a pick of %s in a repository laid out like the mirror', (_what, path, held) => {
+ const root = scratch('point-release-hold-');
+ git(root, 'init', '-q', '-b', 'main');
+ configureTestGitRepository(root, (args) => git(root, ...args));
+ writeFileSync(join(root, 'README.md'), 'stable\n');
+ git(root, 'add', '-A');
+ git(root, 'commit', '-q', '-m', 'stable');
+ git(root, 'tag', 'v1.0.0');
+ mkdirSync(join(root, '.github', 'release-holds'), { recursive: true });
+ writeFileSync(join(root, path), 'changed\n');
+ git(root, 'add', '-A');
+ git(root, 'commit', '-q', '-m', 'the pick');
+ const pick = git(root, 'rev-parse', 'HEAD');
+ git(root, 'switch', '-q', '--detach', 'v1.0.0');
+ git(root, 'cherry-pick', pick);
+ const res = spawnSync(
+ process.execPath,
+ [
+ '--input-type=module',
+ '-e',
+ `const { realIo } = await import(${JSON.stringify(pathToFileURL(SCRIPT).href)}); console.log(JSON.stringify(realIo().hold.evaluate('HEAD')));`,
+ ],
+ { cwd: root, encoding: 'utf8', env: cleanEnv },
+ );
+ expect(res.status, res.stderr).toBe(0);
+ expect(JSON.parse(res.stdout)).toMatchObject({ sha: git(root, 'rev-parse', 'HEAD'), held });
+ expectNoAutomaticGitMaintenance(root);
+ });
+
test('an empty BUMP_VERDICTS stops the release run with an error naming the read-bumps output', () => {
const res = runScript(scratch('point-release-empty-verdicts-'), [], { BUMP_VERDICTS: '' });
expect(res.status).toBe(1);
diff --git a/.github/scripts/release-hold-shape.test.mjs b/.github/scripts/release-hold-shape.test.mjs
new file mode 100644
index 000000000..bef1c308c
--- /dev/null
+++ b/.github/scripts/release-hold-shape.test.mjs
@@ -0,0 +1,295 @@
+// biome-ignore-all lint/suspicious/noTemplateCurlyInString: shell and GitHub expression fixtures must remain literal.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, posix } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterAll, describe, expect, test } from 'vitest';
+import { parse } from 'yaml';
+import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';
+import { configureTestGitRepository } from '../../test-support/configure-git-fixture.test-helper.ts';
+import { expectNoAutomaticGitMaintenance } from './git-fixture-maintenance.test-helper.mjs';
+import { RELEASE_HOLD_SENTINEL } from './release-hold.mjs';
+
+const SCRIPTS = dirname(fileURLToPath(import.meta.url));
+const OK_ROOT = join(SCRIPTS, '..', '..');
+const GUARD = '.github/scripts/release-hold.mjs';
+const PUBLISHES = /gh release (create|edit|upload) |--draft=false|\/dispatches|npm publish |git tag "|push origin "/;
+const workflow = (name) => parse(readFileSync(join(OK_ROOT, '.github', 'workflows', name), 'utf8'));
+const stepsOf = (file, job) => {
+ const steps = workflow(file).jobs?.[job]?.steps;
+ if (!Array.isArray(steps) || steps.length < 3) throw new Error(`${file} job ${job} has no step list to inspect`);
+ return steps;
+};
+const holdSteps = (steps) => steps.filter((step) => String(step.run ?? '').includes('release-hold.mjs'));
+const onlyHoldStep = (steps) => {
+ const found = holdSteps(steps);
+ expect(found).toHaveLength(1);
+ expect(found[0]['continue-on-error']).toBeUndefined();
+ return found[0];
+};
+const indexWhere = (steps, predicate, what) => {
+ const index = steps.findIndex(predicate);
+ if (index === -1) throw new Error(`no step ${what}`);
+ return index;
+};
+const publishingJobs = (file) =>
+ Object.entries(workflow(file).jobs)
+ .filter(([, job]) => (job.steps ?? []).some((step) => PUBLISHES.test(String(step.run ?? ''))))
+ .map(([name]) => name)
+ .sort();
+const archivedModules = (run) => /git archive "\$GITHUB_SHA" ([^|]+)\|/.exec(run)[1].trim().split(/\s+/);
+const importClosure = (entry) => {
+ const pending = [entry];
+ const needed = new Set();
+ while (pending.length > 0) {
+ const file = pending.pop();
+ if (needed.has(file)) continue;
+ needed.add(file);
+ const source = readFileSync(join(OK_ROOT, file), 'utf8');
+ for (const [, specifier] of source.matchAll(/^import [^;]*? from '(\.{1,2}\/[^']+)';$/gms)) {
+ pending.push(posix.normalize(posix.join(posix.dirname(file), specifier)));
+ }
+ }
+ return [...needed].sort();
+};
+
+const scratch = [];
+afterAll(() => {
+ while (scratch.length > 0) rmSync(scratch.pop(), { recursive: true, force: true });
+});
+
+function mirrorFixture() {
+ const root = realpathSync(mkdtempSync(join(tmpdir(), 'ok-release-hold-mirror-')));
+ scratch.push(root);
+ const env = gitCleanEnv();
+ const git = (...args) =>
+ execFileSync('git', ['-c', 'user.name=t', '-c', '[email protected]', '-c', 'commit.gpgsign=false', ...args], {
+ cwd: root,
+ env,
+ encoding: 'utf8',
+ stdio: 'pipe',
+ }).trim();
+ const write = (path, content) => {
+ mkdirSync(dirname(join(root, path)), { recursive: true });
+ writeFileSync(join(root, path), content);
+ };
+ const commit = (message, files) => {
+ for (const [path, content] of Object.entries(files)) write(path, content);
+ git('add', '-A');
+ git('commit', '--quiet', '-m', message);
+ return git('rev-parse', 'HEAD');
+ };
+ git('init', '--quiet', '--initial-branch=main');
+ env.GIT_TRACE2_EVENT = join(root, '.git', 'fixture-maintenance.jsonl');
+ configureTestGitRepository(root, (args) => git(...args));
+ commit('chore: the shipped change (#100)', { 'README.md': 'stable\n' });
+ git('tag', 'v1.0.0');
+ commit('ci: add the release hold guard (#150)', Object.fromEntries(importClosure(GUARD).map((file) => [file, readFileSync(join(OK_ROOT, file))])));
+ git('tag', 'v1.0.1-beta.0');
+ commit('feat: boot only the converged host (#200)', { [RELEASE_HOLD_SENTINEL]: 'held\n' });
+ git('tag', 'v1.1.0-beta.0');
+ git('tag', 'v1.1.0');
+ const postFlipFix = commit('fix: a post-flip fix (#201)', { 'post-flip-fix.txt': 'fixed\n' });
+ git('switch', '--quiet', '--detach', 'v1.0.0');
+ git('cherry-pick', postFlipFix);
+ git('tag', 'v1.0.1');
+ git('switch', '--quiet', 'main');
+ return { root, git, env, workflowSha: git('rev-parse', 'HEAD') };
+}
+
+function runStep(step, { cwd, env }) {
+ const runnerTemp = realpathSync(mkdtempSync(join(tmpdir(), 'ok-release-hold-runner-')));
+ scratch.push(runnerTemp);
+ const script = join(runnerTemp, 'step.sh');
+ writeFileSync(script, step.run);
+ return spawnSync('bash', ['--noprofile', '--norc', '-eo', 'pipefail', script], {
+ cwd,
+ encoding: 'utf8',
+ env: { ...gitCleanEnv(), RUNNER_TEMP: runnerTemp, ...env },
+ });
+}
+
+describe('promote-stable refuses a held beta before it tags', () => {
+ const steps = stepsOf('promote-stable.yml', 'promote');
+ const hold = onlyHoldStep(steps);
+
+ test('it reads the beta commit promote-stable would tag, and reports main', () => {
+ expect(hold.run).toBe(
+ 'node .github/scripts/release-hold.mjs --candidate "$BETA_SHA" --label "${STABLE_TAG} from ${BETA_TAG}" --main HEAD',
+ );
+ expect(hold.env).toEqual({
+ BETA_TAG: '${{ steps.resolve.outputs.beta_tag }}',
+ BETA_SHA: '${{ steps.ver.outputs.beta_sha }}',
+ STABLE_TAG: '${{ steps.ver.outputs.stable_tag }}',
+ });
+ });
+
+ test('it runs whenever the promotion would tag, and every tag and publish step comes after it', () => {
+ const compute = indexWhere(steps, (step) => step.id === 'ver', 'with id ver');
+ const tag = indexWhere(steps, (step) => step.name === 'Tag stable at beta SHA', 'that tags');
+ expect(steps.indexOf(hold)).toBeGreaterThan(compute);
+ expect(hold.if).toBe(steps[tag].if);
+ const publishing = steps.filter((step) => PUBLISHES.test(String(step.run ?? '')));
+ expect(publishing.length).toBeGreaterThanOrEqual(3);
+ for (const step of publishing) expect(steps.indexOf(step)).toBeGreaterThan(steps.indexOf(hold));
+ expect(publishingJobs('promote-stable.yml')).toEqual(['promote']);
+ });
+});
+
+describe('desktop-release refuses a held stable tag in prepare and again in finalize', () => {
+ const release = workflow('desktop-release.yml');
+ const prepare = stepsOf('desktop-release.yml', 'prepare');
+ const finalize = stepsOf('desktop-release.yml', 'finalize');
+ const prepareHold = onlyHoldStep(prepare);
+ const finalizeHold = onlyHoldStep(finalize);
+
+ test('prepare checks the stable channel only, against the release tag, after the channel is known', () => {
+ expect(prepareHold.if).toBe("steps.channel.outputs.channel == 'latest'");
+ expect(prepareHold.env.RELEASE_TAG).toBe('${{ github.event.client_payload.release_tag || inputs.release_tag }}');
+ expect(prepareHold.run).toContain('--candidate "refs/tags/${RELEASE_TAG}"');
+ expect(prepare.indexOf(prepareHold)).toBeGreaterThan(indexWhere(prepare, (step) => step.id === 'channel', 'with id channel'));
+ });
+
+ test('prepare loads the guard from the workflow revision, with every module it imports', () => {
+ expect(prepareHold.run).toMatch(/git archive "\$GITHUB_SHA" [^\n]*\.github\/scripts\/release-hold\.mjs/);
+ expect(prepareHold.run).toMatch(/node "\$hold\/\.github\/scripts\/release-hold\.mjs"/);
+ expect(archivedModules(prepareHold.run).sort()).toEqual(importClosure(GUARD));
+ });
+
+ test('finalize checks again, from the workflow revision with every tag, before it publishes anything', () => {
+ expect(finalizeHold.if).toBe("success() && needs.prepare.outputs.channel == 'latest'");
+ expect(finalizeHold.run).toBe('node .github/scripts/release-hold.mjs --candidate "refs/tags/${RELEASE_TAG}" --label "$RELEASE_TAG"');
+ expect(release.jobs.finalize.env.RELEASE_TAG).toBe('${{ github.event.client_payload.release_tag || inputs.release_tag }}');
+ const [checkout] = finalize.filter((step) => step.uses?.startsWith('actions/checkout@'));
+ expect(checkout.with?.['fetch-depth']).toBe(0);
+ expect(checkout.with?.ref).toBeUndefined();
+ expect(finalize.indexOf(checkout)).toBeLessThan(finalize.indexOf(finalizeHold));
+ const shipping = finalize.filter((step) => /--draft=false|\/dispatches|curl /.test(String(step.run ?? '')));
+ expect(shipping.length).toBeGreaterThanOrEqual(4);
+ for (const step of shipping) expect(finalize.indexOf(step)).toBeGreaterThan(finalize.indexOf(finalizeHold));
+ });
+
+ test('every job that uploads, publishes or dispatches runs only after prepare succeeded', () => {
+ expect(publishingJobs('desktop-release.yml')).toEqual(['finalize', 'publish-assets', 'release-consumers']);
+ expect(release.jobs['publish-assets'].needs).toContain('prepare');
+ expect(release.jobs['publish-assets'].if).toContain("needs.prepare.result == 'success'");
+ expect(release.jobs.finalize.needs).toEqual(expect.arrayContaining(['prepare', 'publish-assets']));
+ expect(release.jobs.finalize.if).toContain("needs.publish-assets.result == 'success'");
+ expect(release.jobs['release-consumers'].needs).toBe('finalize');
+ expect(release.jobs['release-consumers'].if).toContain("needs.finalize.outputs.published == 'true'");
+ });
+});
+
+describe('release.yml refuses to publish a held stable to npm', () => {
+ const release = workflow('release.yml');
+ const build = stepsOf('release.yml', 'build');
+ const hold = onlyHoldStep(build);
+
+ test('the build job checks the stable tag it checked out, on the publish-stable path only', () => {
+ expect(hold.if).toBe("github.event.action == 'publish-stable'");
+ expect(hold.run).toContain('--candidate HEAD');
+ const [checkout] = build.filter((step) => step.uses?.startsWith('actions/checkout@'));
+ expect(checkout.with.ref).toMatch(/^\$\{\{ github\.event\.client_payload\.ref \|\| /);
+ expect(build.indexOf(checkout)).toBeLessThan(build.indexOf(hold));
+ expect(archivedModules(hold.run).sort()).toEqual(importClosure(GUARD));
+ });
+
+ test('tagging and npm publication need the build job, with no condition that outlives its failure', () => {
+ expect(publishingJobs('release.yml')).toEqual(['publish', 'release']);
+ for (const name of ['release', 'publish']) {
+ expect(release.jobs[name].needs).toContain('build');
+ expect(release.jobs[name].if).not.toMatch(/always\(\)|cancelled\(\)|failure\(\)/);
+ }
+ });
+});
+
+describe('the selector, the point release and the bug lane run the guard inside their scripts', () => {
+ test('the selector step and the planner step are the scripts that hold the guard', () => {
+ const select = stepsOf('select-beta-to-promote.yml', 'evaluate').find((step) => step.id === 'select');
+ expect(select.run).toBe('node .github/scripts/select-beta-to-promote.mjs');
+ const plan = stepsOf('point-release.yml', 'point-release').find((step) => step.id === 'plan');
+ expect(plan.run).toBe('node .github/scripts/point-release-plan.mjs');
+ expect(publishingJobs('select-beta-to-promote.yml')).toEqual([]);
+ expect(publishingJobs('point-release.yml')).toEqual([]);
+ });
+
+ test("the bug lane's evaluator checks out full history, so every pick's first parent is present", () => {
+ const steps = stepsOf('bug-lane.yml', 'bug-lane');
+ const evaluate = steps.find((step) => step.id === 'evaluate');
+ expect(evaluate.run).toBe('node .github/scripts/bug-lane.mjs');
+ const checkouts = steps.filter((step) => step.uses?.startsWith('actions/checkout@'));
+ expect(checkouts).toHaveLength(1);
+ expect(checkouts[0].with?.['fetch-depth']).toBe(0);
+ expect(steps.indexOf(checkouts[0])).toBeLessThan(steps.indexOf(evaluate));
+ const handoff = steps.find((step) => String(step.run ?? '').includes('gh workflow run bug-lane-verify.yml'));
+ expect(handoff.if).toContain("steps.evaluate.outputs.fix_refs != ''");
+ });
+});
+
+describe('each workflow step runs the guard against a repository laid out like inkeep/open-knowledge', () => {
+ const fixture = mirrorFixture();
+ const promoteHold = onlyHoldStep(stepsOf('promote-stable.yml', 'promote'));
+ const prepareHold = onlyHoldStep(stepsOf('desktop-release.yml', 'prepare'));
+ const finalizeHold = onlyHoldStep(stepsOf('desktop-release.yml', 'finalize'));
+ const publishHold = onlyHoldStep(stepsOf('release.yml', 'build'));
+ const at = (ref) => fixture.git('rev-parse', `${ref}^{commit}`);
+ const checkout = (ref) => fixture.git('switch', '--quiet', '--detach', ref);
+
+ test('fixture Git operations do not launch automatic maintenance', () => {
+ expect(() => expectNoAutomaticGitMaintenance(fixture.root, fixture.env)).not.toThrow();
+ });
+
+ test('promote-stable admits a beta without the sentinel and refuses one that carries it', () => {
+ checkout('main');
+ const env = { BETA_TAG: 'v1.0.1-beta.0', BETA_SHA: at('v1.0.1-beta.0'), STABLE_TAG: 'v1.0.1' };
+ const admitted = runStep(promoteHold, { cwd: fixture.root, env });
+ expect(admitted.status, admitted.stdout + admitted.stderr).toBe(0);
+ expect(admitted.stdout).toContain(`v1.0.1 from v1.0.1-beta.0 (${env.BETA_SHA.slice(0, 12)}) does not carry ${RELEASE_HOLD_SENTINEL}`);
+ expect(admitted.stdout).toContain(`::notice::Release hold in force: HEAD carries ${RELEASE_HOLD_SENTINEL}`);
+ const held = runStep(promoteHold, {
+ cwd: fixture.root,
+ env: { BETA_TAG: 'v1.1.0-beta.0', BETA_SHA: at('v1.1.0-beta.0'), STABLE_TAG: 'v1.1.0' },
+ });
+ expect(held.status).toBe(2);
+ expect(held.stdout).toContain('::error::v1.1.0 from v1.1.0-beta.0');
+ });
+
+ test('a sentinel-carrying beta tag is not a stable to desktop-release, so it still builds as a beta', () => {
+ const channel = stepsOf('desktop-release.yml', 'prepare').find((step) => step.id === 'channel');
+ const output = join(fixture.root, '.git', 'channel-output');
+ writeFileSync(output, '');
+ const res = runStep(channel, { cwd: fixture.root, env: { RELEASE_TAG: 'v1.1.0-beta.0', GITHUB_OUTPUT: output } });
+ expect(res.status, res.stderr).toBe(0);
+ expect(readFileSync(output, 'utf8')).toContain('channel=beta\n');
+ expect(prepareHold.if).toBe("steps.channel.outputs.channel == 'latest'");
+ });
+
+ test.each([
+ ['the pre-flip stable', 'v1.0.0', 0],
+ ['a hotfix stable over it carrying a post-flip fix', 'v1.0.1', 0],
+ ['a stable tagged on the flip', 'v1.1.0', 2],
+ ])('prepare, from a checkout of the tag, and finalize, from the workflow revision: %s', (_what, tag, status) => {
+ checkout(tag);
+ const prepared = runStep(prepareHold, { cwd: fixture.root, env: { RELEASE_TAG: tag, GITHUB_SHA: fixture.workflowSha } });
+ expect(prepared.status, prepared.stdout + prepared.stderr).toBe(status);
+ checkout('main');
+ const finalized = runStep(finalizeHold, { cwd: fixture.root, env: { RELEASE_TAG: tag } });
+ expect(finalized.status, finalized.stdout + finalized.stderr).toBe(status);
+ for (const res of [prepared, finalized]) {
+ expect(res.stdout).toContain(status === 0 ? 'so the release hold does not apply.' : `::error::${tag} (`);
+ }
+ });
+
+ test.each([
+ ['v1.0.0', 0],
+ ['v1.0.1', 0],
+ ['v1.1.0', 2],
+ ])('the npm publish-stable build of %s, from a checkout of the tag', (tag, status) => {
+ checkout(tag);
+ const res = runStep(publishHold, { cwd: fixture.root, env: { STABLE_REF: tag, GITHUB_SHA: fixture.workflowSha } });
+ expect(res.status, res.stdout + res.stderr).toBe(status);
+ expect(res.stdout).toContain(status === 0 ? `${tag} (${at(tag).slice(0, 12)}) does not carry` : `::error::${tag} (`);
+ checkout('main');
+ });
+});
diff --git a/.github/scripts/release-hold.mjs b/.github/scripts/release-hold.mjs
new file mode 100644
index 000000000..9862aaf48
--- /dev/null
+++ b/.github/scripts/release-hold.mjs
@@ -0,0 +1,186 @@
+/* biome-ignore-all lint/suspicious/noUndeclaredEnvVars: GitHub Actions invokes this entrypoint directly, outside Turbo. */
+import { spawnSync } from 'node:child_process';
+import { appendFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';
+
+export const RELEASE_HOLD_SENTINEL = '.github/release-holds/converged-host';
+export const REFUSED_EXIT = 2;
+export const SHALLOW_BOUNDARY = 'shallow-boundary';
+
+const FULL_SHA_RE = /^[0-9a-f]{40}$/;
+const shortSha = (sha) => sha.slice(0, 12);
+
+export function gitReader(cwd = process.cwd()) {
+ const run = (args, input) => {
+ const res = spawnSync('git', ['--no-replace-objects', ...args], {
+ cwd,
+ env: gitCleanEnv(),
+ encoding: 'utf8',
+ input,
+ maxBuffer: 64 * 1024 * 1024,
+ });
+ if (res.error) throw new Error(`git ${args[0]} could not run: ${res.error.message}`);
+ return res;
+ };
+ const failed = (args, res) =>
+ new Error(
+ `git ${args.join(' ')} failed (exit ${res.status ?? res.signal}): ${String(res.stderr || '').trim()}`,
+ );
+ const read = (args, input) => {
+ const res = run(args, input);
+ if (res.status !== 0) throw failed(args, res);
+ return res.stdout;
+ };
+
+ return {
+ resolveCommit(ref) {
+ const args = ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`];
+ const res = run(args);
+ if (res.status === 0) return res.stdout.trim();
+ if (res.status !== 1) throw failed(args, res);
+ throw new Error(`${ref} does not resolve to a commit in this checkout`);
+ },
+ objectType(sha) {
+ const line = read(['cat-file', '--batch-check=%(objectname) %(objecttype)'], `${sha}\n`).trim();
+ const [, type = 'missing'] = line.split(' ');
+ return type === 'missing' ? null : type;
+ },
+ parents(sha) {
+ const parents = [];
+ for (const line of read(['cat-file', 'commit', sha]).split('\n')) {
+ if (line === '') break;
+ if (line.startsWith('parent ')) parents.push(line.slice('parent '.length));
+ }
+ if (!parents.every((parent) => FULL_SHA_RE.test(parent))) {
+ throw new Error(`commit ${sha} records a parent that is not a full object name`);
+ }
+ return parents;
+ },
+ treeHas(sha, path) {
+ return read(['ls-tree', '--full-tree', '-z', sha, '--', path]) !== '';
+ },
+ };
+}
+
+export function evaluateTree({ candidate, git, path = RELEASE_HOLD_SENTINEL }) {
+ const sha = git.resolveCommit(candidate);
+ return { kind: 'tree', candidate, sha, path, held: git.treeHas(sha, path) };
+}
+
+export function evaluatePick({ candidate, git, path = RELEASE_HOLD_SENTINEL }) {
+ const sha = git.resolveCommit(candidate);
+ const [firstParent = null] = git.parents(sha);
+ if (firstParent !== null && git.objectType(firstParent) !== 'commit') {
+ throw Object.assign(
+ new Error(
+ `${candidate} (${shortSha(sha)}) names first parent ${shortSha(firstParent)}, which is not in this ` +
+ `clone, as at a shallow boundary, so whether it adds ${path} cannot be read. Fetch full history ` +
+ '(fetch-depth: 0) and run the check again.',
+ ),
+ { code: SHALLOW_BOUNDARY },
+ );
+ }
+ const carries = git.treeHas(sha, path);
+ const parentCarries = firstParent === null ? false : git.treeHas(firstParent, path);
+ return { kind: 'pick', candidate, sha, firstParent, path, held: carries && !parentCarries };
+}
+
+export function holdHeadline(verdict, label = verdict.candidate) {
+ const what =
+ verdict.kind === 'pick'
+ ? `adds ${verdict.path} against its first parent`
+ : `carries ${verdict.path}`;
+ return (
+ `${label} (${shortSha(verdict.sha)}) ${what}, the release hold the converged local host arms, so it ` +
+ 'is not published as a stable. See RELEASES.md, "Release hold".'
+ );
+}
+
+export function describeHold(verdict, label = verdict.candidate) {
+ if (verdict.held) return holdHeadline(verdict, label);
+ const what =
+ verdict.kind === 'pick'
+ ? `does not add ${verdict.path} against its first parent ${shortSha(verdict.firstParent ?? 'none')}`
+ : `does not carry ${verdict.path}`;
+ return `${label} (${shortSha(verdict.sha)}) ${what}, so the release hold does not apply.`;
+}
+
+export function mainHoldReport({ ref, git, path = RELEASE_HOLD_SENTINEL }) {
+ let carries;
+ try {
+ carries = git.treeHas(git.resolveCommit(ref), path);
+ } catch (err) {
+ return `::warning::Release hold: could not read whether ${ref} carries ${path} (${err.message}).`;
+ }
+ return carries
+ ? `::notice::Release hold in force: ${ref} carries ${path}, so no beta cut from it is published as a stable until the hold's release PR removes the file.`
+ : `Release hold not in force: ${ref} does not carry ${path}.`;
+}
+
+const VALUE_FLAGS = new Set(['--candidate', '--pick', '--label', '--main', '-C']);
+
+export function parseArgs(argv) {
+ const options = {};
+ for (let i = 0; i < argv.length; i += 1) {
+ const flag = argv[i];
+ if (!VALUE_FLAGS.has(flag)) throw new Error(`unrecognized argument: ${flag}`);
+ const value = argv[i + 1];
+ if (value === undefined || VALUE_FLAGS.has(value)) throw new Error(`${flag} needs a value`);
+ if (flag in options) throw new Error(`${flag} was given twice`);
+ options[flag] = value;
+ i += 1;
+ }
+ if ('--candidate' in options === '--pick' in options) {
+ throw new Error('give exactly one of --candidate <ref> or --pick <ref>');
+ }
+ return {
+ kind: '--pick' in options ? 'pick' : 'tree',
+ candidate: options['--candidate'] ?? options['--pick'],
+ label: options['--label'] ?? null,
+ main: options['--main'] ?? null,
+ cwd: options['-C'] ?? null,
+ };
+}
+
+function main() {
+ let options;
+ try {
+ options = parseArgs(process.argv.slice(2));
+ } catch (err) {
+ console.error(
+ `::error::release-hold: ${err.message}. Usage: --candidate <ref> | --pick <ref>, with optional ` +
+ '--label <name>, --main <ref> and -C <git dir>.',
+ );
+ process.exit(1);
+ }
+
+ const git = gitReader(options.cwd ?? process.cwd());
+ const label = options.label ?? options.candidate;
+ let verdict;
+ try {
+ const evaluate = options.kind === 'pick' ? evaluatePick : evaluateTree;
+ verdict = evaluate({ candidate: options.candidate, git });
+ } catch (err) {
+ console.log(`::error::release-hold could not decide, so ${label} is held: ${err.message}`);
+ process.exit(1);
+ }
+
+ if (options.main !== null) console.log(mainHoldReport({ ref: options.main, git }));
+ const line = describeHold(verdict, label);
+ if (process.env.GITHUB_STEP_SUMMARY) {
+ appendFileSync(
+ process.env.GITHUB_STEP_SUMMARY,
+ `### Release hold: ${label} ${verdict.held ? 'held' : 'not held'}\n\n${line}\n`,
+ );
+ }
+ if (verdict.held) {
+ console.log(`::error::${line}`);
+ process.exit(REFUSED_EXIT);
+ }
+ console.log(line);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ main();
+}
diff --git a/.github/scripts/release-hold.test.mjs b/.github/scripts/release-hold.test.mjs
new file mode 100644
index 000000000..282993d64
--- /dev/null
+++ b/.github/scripts/release-hold.test.mjs
@@ -0,0 +1,285 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterAll, describe, expect, test } from 'vitest';
+import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';
+import { configureTestGitRepository } from '../../test-support/configure-git-fixture.test-helper.ts';
+import { expectNoAutomaticGitMaintenance } from './git-fixture-maintenance.test-helper.mjs';
+import {
+ describeHold,
+ evaluatePick,
+ evaluateTree,
+ gitReader,
+ holdHeadline,
+ mainHoldReport,
+ parseArgs,
+ REFUSED_EXIT,
+ RELEASE_HOLD_SENTINEL,
+ SHALLOW_BOUNDARY,
+} from './release-hold.mjs';
+
+const SCRIPT = fileURLToPath(new URL('./release-hold.mjs', import.meta.url));
+const scratch = [];
+
+afterAll(() => {
+ while (scratch.length > 0) rmSync(scratch.pop(), { recursive: true, force: true });
+});
+
+function tempDir(prefix) {
+ const dir = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+ scratch.push(dir);
+ return dir;
+}
+
+function makeRepo(dir = tempDir('ok-release-hold-')) {
+ const fixtureEnv = gitCleanEnv();
+ const git = (...args) =>
+ execFileSync(
+ 'git',
+ ['-c', 'user.name=Release Bot', '-c', '[email protected]', '-c', 'commit.gpgsign=false', ...args],
+ { cwd: dir, env: fixtureEnv, encoding: 'utf8', stdio: 'pipe' },
+ ).trim();
+ git('init', '--quiet', '--initial-branch=main');
+ fixtureEnv.GIT_TRACE2_EVENT = join(dir, '.git', 'fixture-maintenance.jsonl');
+ configureTestGitRepository(dir, (args) => git(...args));
+ const write = (path, content) => {
+ mkdirSync(dirname(join(dir, path)), { recursive: true });
+ writeFileSync(join(dir, path), content);
+ };
+ const commit = (message, files = {}, removed = []) => {
+ for (const [path, content] of Object.entries(files)) write(path, content);
+ for (const path of removed) git('rm', '--quiet', path);
+ git('add', '-A');
+ git('commit', '--quiet', '--allow-empty', '-m', message);
+ return git('rev-parse', 'HEAD');
+ };
+ return { dir, git, commit, reader: gitReader(dir) };
+}
+
+function releaseLine() {
+ const repo = makeRepo();
+ const stable = repo.commit('chore: the shipped change (#100)', { 'README.md': 'stable\n' });
+ repo.git('tag', 'v1.0.0');
+ const preFlipBeta = repo.commit('fix: a pre-flip fix (#101)', { 'fix.txt': 'pre-flip\n' });
+ repo.git('tag', 'v1.0.1-beta.0');
+ const flip = repo.commit('feat: boot only the converged host (#200)', {
+ [RELEASE_HOLD_SENTINEL]: 'held\n',
+ 'host.txt': 'converged\n',
+ });
+ repo.git('tag', 'v1.1.0-beta.0');
+ const postFlipFix = repo.commit('fix: a post-flip fix (#201)', { 'post-flip-fix.txt': 'post-flip\n' });
+ repo.git('tag', 'v1.1.0-beta.1');
+ const release = repo.commit('chore: release the converged-host hold (#202)', {}, [RELEASE_HOLD_SENTINEL]);
+ repo.git('tag', 'v1.1.0-beta.2');
+ return { ...repo, stable, preFlipBeta, flip, postFlipFix, release };
+}
+
+const runCli = (args, { cwd, env = {} } = {}) => {
+ const summary = join(tempDir('ok-release-hold-summary-'), 'summary.md');
+ writeFileSync(summary, '');
+ const res = spawnSync(process.execPath, [SCRIPT, ...args], {
+ cwd,
+ encoding: 'utf8',
+ env: { ...gitCleanEnv(), GITHUB_STEP_SUMMARY: summary, ...env },
+ });
+ return { ...res, summary: readFileSync(summary, 'utf8') };
+};
+
+describe('a tree candidate: a beta or stable tag, or a synthetic commit', () => {
+ const line = releaseLine();
+
+ test('fixture Git operations do not launch automatic maintenance', () => {
+ expect(() => expectNoAutomaticGitMaintenance(line.dir)).not.toThrow();
+ });
+
+ test('a stable cut before the flip is not held, and says so', () => {
+ const verdict = evaluateTree({ candidate: 'refs/tags/v1.0.0', git: line.reader });
+ expect(verdict).toEqual({
+ kind: 'tree',
+ candidate: 'refs/tags/v1.0.0',
+ sha: line.stable,
+ path: RELEASE_HOLD_SENTINEL,
+ held: false,
+ });
+ expect(describeHold(verdict, 'v1.0.0')).toBe(
+ `v1.0.0 (${line.stable.slice(0, 12)}) does not carry ${RELEASE_HOLD_SENTINEL}, so the release hold does not apply.`,
+ );
+ });
+
+ test('a pre-flip beta is not held', () => {
+ expect(evaluateTree({ candidate: 'v1.0.1-beta.0', git: line.reader }).held).toBe(false);
+ });
+
+ test('a beta carrying the sentinel is held, and so is every later beta until the release PR', () => {
+ const verdict = evaluateTree({ candidate: 'v1.1.0-beta.0', git: line.reader });
+ expect(verdict.held).toBe(true);
+ expect(holdHeadline(verdict, 'v1.1.0 from v1.1.0-beta.0')).toBe(
+ `v1.1.0 from v1.1.0-beta.0 (${line.flip.slice(0, 12)}) carries ${RELEASE_HOLD_SENTINEL}, the release hold ` +
+ 'the converged local host arms, so it is not published as a stable. See RELEASES.md, "Release hold".',
+ );
+ expect(evaluateTree({ candidate: 'v1.1.0-beta.1', git: line.reader }).held).toBe(true);
+ });
+
+ test('the release PR that deletes the sentinel lifts the hold', () => {
+ expect(evaluateTree({ candidate: 'v1.1.0-beta.2', git: line.reader }).held).toBe(false);
+ });
+
+ test('a hotfix stable cut over the pre-flip stable with a post-flip fix is not held', () => {
+ const repo = releaseLine();
+ repo.git('switch', '--quiet', '--detach', 'v1.0.0');
+ repo.git('cherry-pick', repo.postFlipFix);
+ repo.git('tag', 'v1.0.1');
+ expect(evaluateTree({ candidate: 'refs/tags/v1.0.1', git: repo.reader }).held).toBe(false);
+ });
+
+ test('a sentinel that is a directory still holds', () => {
+ const repo = makeRepo();
+ repo.commit('add a directory at the sentinel path', { [`${RELEASE_HOLD_SENTINEL}/marker`]: 'held\n' });
+ expect(evaluateTree({ candidate: 'HEAD', git: repo.reader }).held).toBe(true);
+ });
+
+ test('a candidate that does not resolve to a commit cannot be decided', () => {
+ expect(() => evaluateTree({ candidate: 'v9.9.9', git: line.reader })).toThrow(
+ 'v9.9.9 does not resolve to a commit in this checkout',
+ );
+ });
+
+ test('a candidate whose tree object is missing cannot be decided', () => {
+ const repo = makeRepo();
+ const sha = repo.commit('one commit', { 'README.md': 'stable\n' });
+ const tree = repo.git('rev-parse', `${sha}^{tree}`);
+ unlinkSync(join(repo.dir, '.git', 'objects', tree.slice(0, 2), tree.slice(2)));
+ expect(() => evaluateTree({ candidate: sha, git: repo.reader })).toThrow(/git ls-tree .* failed/);
+ });
+
+ test('a git read that fails outright cannot be decided', () => {
+ const notARepo = tempDir('ok-release-hold-not-a-repo-');
+ expect(() => evaluateTree({ candidate: 'HEAD', git: gitReader(notARepo) })).toThrow(/failed/);
+ });
+});
+
+describe("a bug-lane pick: the commit's own diff against its first parent", () => {
+ const line = releaseLine();
+
+ test('the commit that brought the flip to main is held', () => {
+ const verdict = evaluatePick({ candidate: line.flip, git: line.reader });
+ expect(verdict).toMatchObject({ kind: 'pick', held: true, firstParent: line.preFlipBeta });
+ expect(holdHeadline(verdict, 'fix')).toContain(`adds ${RELEASE_HOLD_SENTINEL} against its first parent`);
+ });
+
+ test('a fix authored after the flip is not held, though its tree carries the sentinel', () => {
+ const verdict = evaluatePick({ candidate: line.postFlipFix, git: line.reader });
+ expect(verdict).toMatchObject({ held: false, firstParent: line.flip });
+ expect(describeHold(verdict)).toBe(
+ `${line.postFlipFix} (${line.postFlipFix.slice(0, 12)}) does not add ${RELEASE_HOLD_SENTINEL} against its ` +
+ `first parent ${line.flip.slice(0, 12)}, so the release hold does not apply.`,
+ );
+ });
+
+ test('a pre-flip fix and the release PR are not held', () => {
+ expect(evaluatePick({ candidate: line.preFlipBeta, git: line.reader }).held).toBe(false);
+ expect(evaluatePick({ candidate: line.release, git: line.reader }).held).toBe(false);
+ });
+
+ test('a merge that brought the flip in on its second parent is held through its first parent', () => {
+ const repo = makeRepo();
+ repo.commit('stable', { 'README.md': 'stable\n' });
+ repo.git('switch', '--quiet', '-c', 'research');
+ repo.commit('the flip', { [RELEASE_HOLD_SENTINEL]: 'held\n' });
+ repo.git('switch', '--quiet', 'main');
+ repo.commit('unrelated work on main', { 'main.txt': 'main\n' });
+ repo.git('merge', '--no-ff', '--quiet', '-m', 'join', 'research');
+ expect(evaluatePick({ candidate: 'HEAD', git: repo.reader }).held).toBe(true);
+ });
+
+ test('a root commit is read against the empty tree', () => {
+ const held = makeRepo();
+ held.commit('root with the sentinel', { [RELEASE_HOLD_SENTINEL]: 'held\n' });
+ expect(evaluatePick({ candidate: 'HEAD', git: held.reader })).toMatchObject({ held: true, firstParent: null });
+ const clear = makeRepo();
+ clear.commit('root without it', { 'README.md': 'stable\n' });
+ expect(evaluatePick({ candidate: 'HEAD', git: clear.reader })).toMatchObject({ held: false, firstParent: null });
+ });
+
+ test('a pick at a shallow boundary is refused, because its first parent is not in the clone', () => {
+ const clone = tempDir('ok-release-hold-shallow-');
+ execFileSync('git', ['clone', '--quiet', '--depth', '1', `file://${line.dir}`, clone], {
+ env: gitCleanEnv(),
+ stdio: 'pipe',
+ });
+ configureTestGitRepository(clone);
+ const shallow = gitReader(clone);
+ expect(() => evaluatePick({ candidate: 'HEAD', git: shallow })).toThrow(
+ expect.objectContaining({
+ code: SHALLOW_BOUNDARY,
+ message: expect.stringContaining(
+ `names first parent ${line.postFlipFix.slice(0, 12)}, which is not in this clone, as at a shallow boundary`,
+ ),
+ }),
+ );
+ expect(evaluateTree({ candidate: 'HEAD', git: shallow }).held).toBe(false);
+ });
+});
+
+describe('the command line', () => {
+ const line = releaseLine();
+
+ test('admits a candidate without the sentinel, says so, and writes the step summary', () => {
+ const res = runCli(['--candidate', 'refs/tags/v1.0.0', '--label', 'v1.0.0'], { cwd: line.dir });
+ expect(res.status, res.stderr).toBe(0);
+ expect(res.stdout).toBe(
+ `v1.0.0 (${line.stable.slice(0, 12)}) does not carry ${RELEASE_HOLD_SENTINEL}, so the release hold does not apply.\n`,
+ );
+ expect(res.summary).toContain('### Release hold: v1.0.0 not held');
+ });
+
+ test('refuses a sentinel-carrying beta with exit 2 and an error annotation', () => {
+ const res = runCli(['--candidate', 'v1.1.0-beta.0', '--label', 'v1.1.0 from v1.1.0-beta.0'], { cwd: line.dir });
+ expect(res.status).toBe(REFUSED_EXIT);
+ expect(res.stdout).toContain(`::error::v1.1.0 from v1.1.0-beta.0 (${line.flip.slice(0, 12)}) carries`);
+ expect(res.summary).toContain('### Release hold: v1.1.0 from v1.1.0-beta.0 held');
+ });
+
+ test('--pick reads the diff against the first parent', () => {
+ expect(runCli(['--pick', line.flip], { cwd: line.dir }).status).toBe(REFUSED_EXIT);
+ expect(runCli(['--pick', line.postFlipFix], { cwd: line.dir }).status).toBe(0);
+ });
+
+ test('a candidate it cannot read fails with exit 1 and names the candidate as held', () => {
+ const res = runCli(['--candidate', 'v9.9.9'], { cwd: line.dir });
+ expect(res.status).toBe(1);
+ expect(res.stdout).toContain('::error::release-hold could not decide, so v9.9.9 is held');
+ const outside = runCli(['--candidate', 'HEAD', '-C', tempDir('ok-release-hold-empty-')]);
+ expect(outside.status).toBe(1);
+ });
+
+ test('--main reports whether the hold is in force without changing the verdict', () => {
+ const inForce = runCli(['--candidate', 'v1.0.0', '--main', 'v1.1.0-beta.1'], { cwd: line.dir });
+ expect(inForce.status, inForce.stderr).toBe(0);
+ expect(inForce.stdout).toContain(`::notice::Release hold in force: v1.1.0-beta.1 carries ${RELEASE_HOLD_SENTINEL}`);
+ const lifted = runCli(['--candidate', 'v1.0.0', '--main', 'HEAD'], { cwd: line.dir });
+ expect(lifted.stdout).toContain(`Release hold not in force: HEAD does not carry ${RELEASE_HOLD_SENTINEL}.`);
+ const unreadable = runCli(['--candidate', 'v1.0.0', '--main', 'nope'], { cwd: line.dir });
+ expect(unreadable.status).toBe(0);
+ expect(unreadable.stdout).toContain('::warning::Release hold: could not read whether nope carries');
+ });
+
+ test('mainHoldReport warns rather than throwing when the ref is unreadable', () => {
+ expect(mainHoldReport({ ref: 'nope', git: line.reader })).toMatch(/^::warning::/);
+ });
+
+ test.each([
+ [[], 'give exactly one of --candidate <ref> or --pick <ref>'],
+ [['--candidate', 'a', '--pick', 'b'], 'give exactly one of --candidate <ref> or --pick <ref>'],
+ [['--candidate', 'a', '--candidate', 'b'], '--candidate was given twice'],
+ [['--candidate'], '--candidate needs a value'],
+ [['--candidate', 'a', '--force'], 'unrecognized argument: --force'],
+ ])('rejects %j', (argv, message) => {
+ expect(() => parseArgs(argv)).toThrow(message);
+ const res = runCli(argv, { cwd: line.dir });
+ expect(res.status).toBe(1);
+ expect(res.stderr).toContain(message);
+ });
+});
diff --git a/.github/scripts/select-beta-to-promote.mjs b/.github/scripts/select-beta-to-promote.mjs
index b7f5262b7..0151f026e 100644
--- a/.github/scripts/select-beta-to-promote.mjs
+++ b/.github/scripts/select-beta-to-promote.mjs
@@ -10,6 +10,7 @@ import {
withBumpVerdicts,
} from '../../scripts/compute-stable-version.mjs';
import { gitCleanEnv } from '../../scripts/git-clean-env.mjs';
+import { describeHold, evaluateTree, gitReader, mainHoldReport } from './release-hold.mjs';
import { createShippedFixCheck, refusalHeadline } from './shipped-fix-containment.mjs';
const BETA_TAG_RE = /^v\d+\.\d+\.\d+-beta\.\d+$/;
@@ -172,6 +173,35 @@ export function resolveTier({ armed, verdict, standardTarget, fastTarget }) {
return { tier, target: standardTarget, candidate: tier === 'fast' ? fastTarget : '' };
}
+export function screenReleaseHold({ target, fastTierCandidate, evaluate, log = () => {} }) {
+ let screenedTarget = target;
+ if (target) {
+ const verdict = evaluate(target);
+ if (verdict.held) {
+ log(`::warning::Not dispatching ${target}: ${describeHold(verdict, target)} This tick dispatches nothing.`);
+ screenedTarget = '';
+ } else {
+ log(describeHold(verdict, target));
+ }
+ }
+ if (!fastTierCandidate) return { target: screenedTarget, fastTierCandidate };
+ let verdict;
+ try {
+ verdict = evaluate(fastTierCandidate);
+ } catch (err) {
+ log(
+ `::warning::Fast tier REFUSED for ${fastTierCandidate}: the release-hold check could not decide (${err.message}). Falling back to the 24h tier.`,
+ );
+ return { target: screenedTarget, fastTierCandidate: '' };
+ }
+ if (verdict.held) {
+ log(`::warning::Fast tier REFUSED for ${fastTierCandidate}: ${describeHold(verdict, fastTierCandidate)}`);
+ return { target: screenedTarget, fastTierCandidate: '' };
+ }
+ log(describeHold(verdict, fastTierCandidate));
+ return { target: screenedTarget, fastTierCandidate };
+}
+
export function screenShippedFixes({
target,
fastTierCandidate,
@@ -454,10 +484,18 @@ async function main() {
fastTarget,
});
const soakTier = resolved.tier;
- const shippedFixCheck = createShippedFixCheck();
- const { target, fastTierCandidate } = screenShippedFixes({
+ const holdGit = gitReader();
+ console.log(mainHoldReport({ ref: 'HEAD', git: holdGit }));
+ const unheld = screenReleaseHold({
target: resolved.target,
fastTierCandidate: resolved.candidate,
+ evaluate: memoizeVerdicts((tag) => evaluateTree({ candidate: `refs/tags/${tag}`, git: holdGit })),
+ log: console.log,
+ });
+ const shippedFixCheck = createShippedFixCheck();
+ const { target, fastTierCandidate } = screenShippedFixes({
+ target: unheld.target,
+ fastTierCandidate: unheld.fastTierCandidate,
dispatchWindowOpen: process.env.DISPATCH_WINDOW_OPEN !== 'false',
evaluate: memoizeVerdicts((tag) => shippedFixCheck.evaluate(tag)),
log: console.log,
diff --git a/.github/scripts/select-beta-to-promote.test.mjs b/.github/scripts/select-beta-to-promote.test.mjs
index 9a8e97ff5..98c3fb809 100644
--- a/.github/scripts/select-beta-to-promote.test.mjs
+++ b/.github/scripts/select-beta-to-promote.test.mjs
@@ -16,9 +16,11 @@ import {
parseBetaTags,
readUnshippedBumps,
resolveTier,
+ screenReleaseHold,
screenShippedFixes,
selectPromotion,
} from './select-beta-to-promote.mjs';
+import { RELEASE_HOLD_SENTINEL } from './release-hold.mjs';
const NOW = Date.parse('2026-07-08T20:00:00Z');
const SOAK = 86400;
@@ -612,6 +614,55 @@ test('changeset fixture Git operations do not launch automatic maintenance', ()
expect(() => expectNoAutomaticGitMaintenance(repository)).not.toThrow();
});
+describe('screenReleaseHold (no dispatch of a beta that carries the release hold)', () => {
+ const verdict = (tag, held) => ({ kind: 'tree', candidate: `refs/tags/${tag}`, sha: 'b'.repeat(40), path: RELEASE_HOLD_SENTINEL, held });
+ const screen = (verdicts, { target = 'v1.1.0-beta.0', fastTierCandidate = '' } = {}) => {
+ const lines = [];
+ const result = screenReleaseHold({
+ target,
+ fastTierCandidate,
+ evaluate: (tag) => {
+ const held = verdicts[tag];
+ if (held instanceof Error) throw held;
+ return verdict(tag, held);
+ },
+ log: (line) => lines.push(line),
+ });
+ return { result, lines };
+ };
+
+ test('a 24h selection without the sentinel is dispatched, and the log says the hold does not apply', () => {
+ const { result, lines } = screen({ 'v1.1.0-beta.0': false });
+ expect(result).toEqual({ target: 'v1.1.0-beta.0', fastTierCandidate: '' });
+ expect(lines).toEqual([
+ `v1.1.0-beta.0 (bbbbbbbbbbbb) does not carry ${RELEASE_HOLD_SENTINEL}, so the release hold does not apply.`,
+ ]);
+ });
+
+ test('a 24h selection that carries the sentinel is not dispatched', () => {
+ const { result, lines } = screen({ 'v1.1.0-beta.0': true });
+ expect(result.target).toBe('');
+ expect(lines[0]).toMatch(/^::warning::Not dispatching v1\.1\.0-beta\.0: v1\.1\.0-beta\.0 \(bbbbbbbbbbbb\) carries /);
+ });
+
+ test('a 24h selection it cannot read fails the tick', () => {
+ expect(() => screen({ 'v1.1.0-beta.0': new Error('git ls-tree failed') })).toThrow('git ls-tree failed');
+ });
+
+ test('a fast-tier candidate that carries the sentinel, or that it cannot read, is not smoked', () => {
+ expect(screen({ 'v1.1.0-beta.1': true }, { target: '', fastTierCandidate: 'v1.1.0-beta.1' }).result).toEqual({
+ target: '',
+ fastTierCandidate: '',
+ });
+ const unreadable = screen({ 'v1.1.0-beta.1': new Error('boom') }, { target: '', fastTierCandidate: 'v1.1.0-beta.1' });
+ expect(unreadable.result.fastTierCandidate).toBe('');
+ expect(unreadable.lines[0]).toContain('the release-hold check could not decide (boom)');
+ expect(screen({ 'v1.1.0-beta.1': false }, { target: '', fastTierCandidate: 'v1.1.0-beta.1' }).result.fastTierCandidate).toBe(
+ 'v1.1.0-beta.1',
+ );
+ });
+});
+
describe('screenShippedFixes (no dispatch promote-stable would refuse)', () => {
const refused = (candidate) => ({
ok: false,
@@ -962,6 +1013,7 @@ describe('the selector entry points the two jobs run', () => {
const SCRIPT = realpathSync(fileURLToPath(new URL('./select-beta-to-promote.mjs', import.meta.url)));
const OK_ROOT = join(dirname(SCRIPT), '..', '..');
const COPIED = [
+ '.github/scripts/release-hold.mjs',
'.github/scripts/select-beta-to-promote.mjs',
'.github/scripts/shipped-fix-containment.mjs',
'scripts/compute-stable-version.mjs',
@@ -1157,6 +1209,70 @@ describe('the selector entry points the two jobs run', () => {
expect(res.output).toBe('');
});
+ test('inside the window it dispatches a soaked beta without the release hold, and says the hold is not in force', () => {
+ const { root } = betaRepo();
+ const verdicts = readBumps(root).output.trim().slice('bump_verdicts='.length);
+ const bin = releaseGh({ ages: { 'v1.1.0-beta.0': 10, 'v1.0.1-beta.0': 60 * 25 } });
+ const res = run(isolatedScript(), root, {
+ env: { BUMP_VERDICTS: verdicts, SOAK_SECONDS: '86400', FAST_TIER_ARMED: 'false', DISPATCH_WINDOW_OPEN: 'true' },
+ bin,
+ });
+ expect(res.status, res.stderr).toBe(0);
+ expect(res.output).toContain('target=v1.0.1-beta.0\ntier=soak\n');
+ expect(res.stdout).toContain(`Release hold not in force: HEAD does not carry ${RELEASE_HOLD_SENTINEL}.`);
+ expect(res.stdout).toContain(
+ `v1.0.1-beta.0 (${git(root, 'rev-parse', 'v1.0.1-beta.0^{commit}').slice(0, 12)}) does not carry ${RELEASE_HOLD_SENTINEL}, so the release hold does not apply.`,
+ );
+ });
+
+ test('it does not dispatch a soaked beta that carries the release hold, and says the hold is in force', () => {
+ const { root } = betaRepo();
+ mkdirSync(join(root, '.github', 'release-holds'), { recursive: true });
+ writeFileSync(join(root, RELEASE_HOLD_SENTINEL), 'held\n');
+ git(root, 'add', '-A');
+ git(root, 'commit', '-q', '-m', 'feat: boot only the converged host (#203)');
+ git(root, 'tag', 'v1.1.0-beta.1');
+ const verdicts = readBumps(root).output.trim().slice('bump_verdicts='.length);
+ const bin = releaseGh({ ages: { 'v1.1.0-beta.1': 60 * 25, 'v1.1.0-beta.0': 60 * 26, 'v1.0.1-beta.0': 60 * 27 } });
+ const res = run(isolatedScript(), root, {
+ env: { BUMP_VERDICTS: verdicts, SOAK_SECONDS: '86400', FAST_TIER_ARMED: 'false', DISPATCH_WINDOW_OPEN: 'true' },
+ bin,
+ });
+ expect(res.status, res.stderr).toBe(0);
+ expect(res.output).toContain('target=\ntier=\n');
+ expect(res.stdout).toContain(`::notice::Release hold in force: HEAD carries ${RELEASE_HOLD_SENTINEL}`);
+ expect(res.stdout).toMatch(/::warning::Not dispatching v1\.1\.0-beta\.1: v1\.1\.0-beta\.1 \([0-9a-f]{12}\) carries /);
+ });
+
+ test('it does not nominate a fast-tier candidate that carries the release hold for the smoke', () => {
+ const root = scratch('select-beta-entry-held-fast-');
+ git(root, 'init', '-q', '-b', 'main');
+ configureTestGitRepository(root, (args) => git(root, ...args));
+ mkdirSync(join(root, '.changeset'), { recursive: true });
+ writeFileSync(join(root, '.changeset', 'keep.md'), '---\n"@inkeep/open-knowledge": patch\n---\n\nkeep\n');
+ git(root, 'add', '-A');
+ git(root, 'commit', '-q', '-m', 'chore: the shipped change (#100)');
+ git(root, 'tag', 'v1.0.0');
+ writeFileSync(join(root, '.changeset', 'fix-crash.md'), '---\n"@inkeep/open-knowledge": patch\n---\n\nfix-crash\n');
+ mkdirSync(join(root, '.github', 'release-holds'), { recursive: true });
+ writeFileSync(join(root, RELEASE_HOLD_SENTINEL), 'held\n');
+ git(root, 'add', '-A');
+ git(root, 'commit', '-q', '-m', 'fix: stop the crash (#201)');
+ git(root, 'tag', 'v1.0.1-beta.0');
+ const verdicts = readBumps(root).output.trim().slice('bump_verdicts='.length);
+ const linear = linearStub();
+ const res = run(isolatedScript(), root, {
+ env: { LINEAR_API_KEY: 'placeholder-linear-key', LINEAR_CALLS: linear.calls, BUMP_VERDICTS: verdicts, FAST_TIER_ARMED: 'true', SOAK_SECONDS: '86400' },
+ bin: releaseGh({ ages: { 'v1.0.1-beta.0': 120 } }),
+ preload: linear.preload,
+ });
+ expect(res.status, res.stderr).toBe(0);
+ expect(res.output).toContain('fast_tier_candidate=\nsoak_tier=fast\n');
+ expect(res.output).toContain('fast_candidate=v1.0.1-beta.0\nfast_qualifies=true\n');
+ expect(res.stdout).toMatch(/::warning::Fast tier REFUSED for v1\.0\.1-beta\.0: v1\.0\.1-beta\.0 \([0-9a-f]{12}\) carries /);
+ expect(res.stdout).not.toContain('Fast tier: nominating');
+ });
+
test('inside the window it does not dispatch a soaked beta that lacks a fix a published stable shipped', () => {
const { root } = betaRepo();
git(root, 'switch', '-q', '--detach', 'v1.0.0');
diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml
index 5bd6f5bb2..cf9fc73d1 100644
--- a/.github/workflows/desktop-release.yml
+++ b/.github/workflows/desktop-release.yml
@@ -290,6 +290,19 @@ jobs:
node-version-file: .node-version
package-manager-cache: false
+ - name: Refuse a stable that carries the release hold
+ if: steps.channel.outputs.channel == 'latest'
+ env:
+ RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}
+ run: |
+ set -euo pipefail
+ git cat-file -e "$GITHUB_SHA^{commit}" 2>/dev/null || git fetch --no-tags origin "$GITHUB_SHA"
+ hold="$RUNNER_TEMP/release-hold"
+ rm -rf "$hold"
+ mkdir -p "$hold"
+ git archive "$GITHUB_SHA" .github/scripts/release-hold.mjs scripts/git-clean-env.mjs | tar -x -C "$hold"
+ node "$hold/.github/scripts/release-hold.mjs" --candidate "refs/tags/${RELEASE_TAG}" --label "$RELEASE_TAG"
+
- name: Refuse a stable that lacks a fix a published stable shipped
if: steps.channel.outputs.channel == 'latest'
env:
@@ -1965,6 +1978,10 @@ jobs:
echo "::warning::render-release-downloads.mjs failed for ${RELEASE_TAG}; the release keeps its previous body."
fi
+ - name: Refuse a stable that carries the release hold
+ if: success() && needs.prepare.outputs.channel == 'latest'
+ run: node .github/scripts/release-hold.mjs --candidate "refs/tags/${RELEASE_TAG}" --label "$RELEASE_TAG"
+
- name: Refuse a stable that lacks a fix a published stable shipped
if: success() && needs.prepare.outputs.channel == 'latest'
env:
@@ -2455,6 +2472,6 @@ jobs:
if [[ "$CHANNEL" == "beta" ]]; then
RECOVERY="Follow RELEASES.md, Recovering unpublished beta installers; re-dispatch desktop-release.yml for this tag so the build and inventory gates pass before publication."
else
- RECOVERY="Follow RELEASES.md, Recovery workflow revision and Resuming a blocked cut; stable recovery must publish through a lock-bearing finalize. Never recover a tag the shipped-fix check refused."
+ RECOVERY="Follow RELEASES.md, Recovery workflow revision and Resuming a blocked cut; stable recovery must publish through a lock-bearing finalize. Never recover a tag the shipped-fix check or the release hold refused."
fi
echo "::warning::STUCK-DRAFT: Release ${RELEASE_TAG} may be stuck as draft (channel=${CHANNEL:-unknown}). ${RECOVERY}"
diff --git a/.github/workflows/promote-stable.yml b/.github/workflows/promote-stable.yml
index bfddb95e0..a6eaf06b7 100644
--- a/.github/workflows/promote-stable.yml
+++ b/.github/workflows/promote-stable.yml
@@ -308,6 +308,14 @@ jobs:
# shipped, or adds no changesets) and gates every step below.
node scripts/compute-stable-version.mjs "$BETA_TAG"
+ - name: Refuse a stable that carries the release hold
+ if: steps.ver.outputs.skip != 'true'
+ env:
+ BETA_TAG: ${{ steps.resolve.outputs.beta_tag }}
+ BETA_SHA: ${{ steps.ver.outputs.beta_sha }}
+ STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}
+ run: node .github/scripts/release-hold.mjs --candidate "$BETA_SHA" --label "${STABLE_TAG} from ${BETA_TAG}" --main HEAD
+
- name: Refuse a stable that lacks a fix a published stable shipped
if: steps.ver.outputs.skip != 'true'
env:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a0f9f2d20..c911e7a7e 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -314,6 +314,19 @@ jobs:
node-version-file: .node-version
package-manager-cache: false
+ - name: Refuse a stable that carries the release hold
+ if: github.event.action == 'publish-stable'
+ env:
+ STABLE_REF: ${{ github.event.client_payload.ref }}
+ run: |
+ set -euo pipefail
+ git cat-file -e "$GITHUB_SHA^{commit}" 2>/dev/null || git fetch --no-tags origin "$GITHUB_SHA"
+ hold="$RUNNER_TEMP/release-hold"
+ rm -rf "$hold"
+ mkdir -p "$hold"
+ git archive "$GITHUB_SHA" .github/scripts/release-hold.mjs scripts/git-clean-env.mjs | tar -x -C "$hold"
+ node "$hold/.github/scripts/release-hold.mjs" --candidate HEAD --label "$STABLE_REF"
+
- name: Ensure npm 11 for the cli's package surface check
run: |
npm install -g [email protected]