Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): stamp the stable Linear release by tag containment (PRD-7772) (#3167)

Andrew Mikofalvy954034f6e495
diff --git a/.github/scripts/resolve-shipped-version.mjs b/.github/scripts/resolve-shipped-version.mjs
index 094caf90c..0017abfea 100644
--- a/.github/scripts/resolve-shipped-version.mjs
+++ b/.github/scripts/resolve-shipped-version.mjs
@@ -218,7 +218,7 @@ function runGit(args) {
return String(res.stdout || '');
}
-function realStableTags() {
+export function realStableTags() {
return runGit(['tag', '--list', 'v*', '--sort=version:refname']).split('\n');
}
@@ -228,7 +228,7 @@ function realStableTags() {
const REC_SEP = '\x1e';
const UNIT_SEP = '\x1f';
-function realFindMirroredCommits(privateSha) {
+export function realFindMirroredCommits(privateSha) {
// `--all` rather than HEAD: a point release lives on a synthetic off-`main`
// tag, so the cherry-picked copy of a fix is unreachable from the checked-out
// branch. `--fixed-strings` keeps the SHA from being read as a pattern.
@@ -250,7 +250,7 @@ function realFindMirroredCommits(privateSha) {
return commits;
}
-function realContains(tag, sha) {
+export function realContains(tag, sha) {
// Distinguish a clean "not an ancestor" (exit 1) from an infra failure (any
// other non-zero), which must fail loud rather than read as "not contained".
const res = spawnSync('git', ['merge-base', '--is-ancestor', sha, `${tag}^{commit}`], {
diff --git a/.github/scripts/stamp-by-containment.mjs b/.github/scripts/stamp-by-containment.mjs
new file mode 100644
index 000000000..625aded41
--- /dev/null
+++ b/.github/scripts/stamp-by-containment.mjs
@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+/**
+ * Make the STABLE release on a Linear ticket mean "the earliest stable release
+ * whose history contains the fix".
+ *
+ * Why this exists alongside the release CLI's own sync. `linear-release sync`
+ * answers a different question: "which pull requests fall inside this cut's
+ * scan range". That is a forward, per-cut delta, and it is the right answer for
+ * a BETA — a beta genuinely reports what is new in it. It is the wrong answer
+ * for a stable, where the useful fact is which build a user must install to get
+ * the fix. Nothing in the CLI computes containment, so a ticket lands on
+ * whichever cut happened to sweep it up, and can land on several.
+ *
+ * Why containment is not a date comparison. "The newest release published after
+ * the fix merged" is wrong here: point releases are cut off the previous stable
+ * rather than off `main`, so a higher tag can publish later yet not contain the
+ * commit. Worse, a fix that is cherry-picked onto a point-release line exists at
+ * TWO mirrored commits; comparing only the mainline copy reports a version later
+ * than the one that actually first carried the fix. The shared resolver already
+ * walks every mirrored copy and returns the lowest containing tag, which is why
+ * this imports it rather than re-deriving containment.
+ *
+ * What it will not do.
+ * - It never touches a BETA attachment. Those are correct per-cut deltas.
+ * - It never acts on a ticket whose fix commit cannot be resolved. Refusing is
+ * the same contract the reporter notifier uses: a stamp nobody can verify is
+ * worse than the absence of one, and removing an existing stamp on a hunch
+ * would destroy a possibly-correct human edit.
+ * - It never creates a release. If the containing stable has no release object
+ * the ticket is reported and skipped; minting releases belongs to the cut.
+ *
+ * Arming. Dry run is the default and the credential alone does not arm it: this
+ * writes to a shared workspace, so an operator wiring up a key should not
+ * thereby start rewriting everyone's tickets. Set STAMP_MODE=live for real
+ * writes.
+ *
+ * Usage:
+ * LINEAR_API_KEY=... node .github/scripts/stamp-by-containment.mjs
+ * LINEAR_API_KEY=... STAMP_MODE=live node .github/scripts/stamp-by-containment.mjs
+ *
+ * Must run inside a full clone (`fetch-depth: 0`, `fetch-tags: true`) — the
+ * containment walk needs every stable tag and full history.
+ *
+ * Fail-loud contract, matching the sibling release scripts: "nothing to
+ * reconcile" and "this fix is not in any stable yet" are real ANSWERS and exit
+ * 0. A missing credential is an answer too. Any infra error (Linear
+ * unreachable, a git failure) exits non-zero rather than collapsing into
+ * silence, because a caller cannot tell a quiet run from a broken one.
+ */
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import {
+ realContains,
+ realFindMirroredCommits,
+ realStableTags,
+ resolveShippedVersion,
+} from './resolve-shipped-version.mjs';
+
+const BETA_VERSION_RE = /-beta\.\d+$/;
+const PRIVATE_PR_RE = /github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/;
+const PRIVATE_REPO = 'inkeep/agents-private';
+
+function log(...args) {
+ process.stderr.write(`${args.join(' ')}\n`);
+}
+
+/** A release object is a beta iff its version carries a prerelease counter. */
+export function isBetaRelease(release) {
+ return BETA_VERSION_RE.test(String(release?.version ?? ''));
+}
+
+/**
+ * Decide what to change on one ticket.
+ *
+ * `evidence` is the crux, because two very different situations both yield "no
+ * containing tag" and only one of them justifies removing a stamp:
+ *
+ * shipped - a containing stable was found.
+ * proven-not-shipped - the fix commit WAS located in the mirror and every tag
+ * was walked; none contain it. A stable stamp here names
+ * a release that demonstrably does not carry the fix, so
+ * it is withdrawn.
+ * unresolvable - the fix commit could not be located at all (no linked
+ * pull request, or nothing in the mirror carries its
+ * trailer). This is an absence of evidence, NOT evidence
+ * of absence: a merge-queue artifact SHA, a revert, a
+ * mislinked pull request, or a fix predating the mirror
+ * all land here while the existing stamp may be right.
+ * Nothing is touched.
+ *
+ * Collapsing the last two would silently strip correct stamps, which is the
+ * opposite of what this pass exists to do.
+ *
+ * Returns `{ action, add, remove, reason }` where action is one of
+ * `noop | attach | reattach | skip`.
+ */
+export function planTicketReconciliation({
+ attachedReleases,
+ shippedTag,
+ evidence,
+ releaseByVersion,
+}) {
+ if (evidence === 'unresolvable') {
+ return { action: 'skip', add: [], remove: [], reason: 'unresolvable-fix-commit' };
+ }
+
+ const stables = (attachedReleases ?? []).filter((r) => !isBetaRelease(r));
+
+ if (!shippedTag) {
+ return stables.length === 0
+ ? { action: 'noop', add: [], remove: [], reason: 'not-in-any-stable' }
+ : {
+ action: 'reattach',
+ add: [],
+ remove: stables.map((r) => r.id),
+ reason: 'not-in-any-stable',
+ };
+ }
+
+ const wantVersion = shippedTag.replace(/^v/, '');
+ const want = releaseByVersion.get(wantVersion);
+ if (!want) {
+ return { action: 'skip', add: [], remove: [], reason: `no-release-object:${wantVersion}` };
+ }
+
+ const already = stables.some((r) => r.id === want.id);
+ const wrong = stables.filter((r) => r.id !== want.id);
+ if (already && wrong.length === 0) {
+ return { action: 'noop', add: [], remove: [], reason: 'already-correct' };
+ }
+ return {
+ action: already ? 'reattach' : 'attach',
+ add: already ? [] : [want.id],
+ remove: wrong.map((r) => r.id),
+ reason: `earliest-containing:${wantVersion}`,
+ };
+}
+
+/** Summary counts for the closing report. */
+export function summarize(plans) {
+ const counts = { noop: 0, attach: 0, reattach: 0, skip: 0 };
+ for (const p of plans) counts[p.plan.action] = (counts[p.plan.action] ?? 0) + 1;
+ return counts;
+}
+
+// --- IO shell ---
+
+async function linear(query, variables) {
+ const res = await fetch('https://api.linear.app/graphql', {
+ method: 'POST',
+ headers: {
+ authorization: process.env.LINEAR_API_KEY,
+ 'content-type': 'application/json',
+ },
+ body: JSON.stringify({ query, variables }),
+ signal: AbortSignal.timeout(20_000),
+ });
+ const text = await res.text();
+ if (!res.ok) throw new Error(`linear HTTP ${res.status}: ${text.slice(0, 300)}`);
+ const body = JSON.parse(text);
+ if (body.errors) throw new Error(`linear graphql: ${JSON.stringify(body.errors).slice(0, 400)}`);
+ return body.data;
+}
+
+/**
+ * PR -> merge commit, through the API because the private repo is not checked
+ * out here.
+ *
+ * Distinguishes the two outcomes the caller must not conflate: an unmerged PR
+ * has no fix commit and returns null, while a failed call THROWS. Swallowing a
+ * rate limit or an expired token would make every ticket look unlinked, and the
+ * run would report a wall of benign-looking skips instead of going red.
+ *
+ * Separate from the sibling resolver's equivalent because this one has to
+ * inject the cross-repo token the bridge App mints.
+ */
+function prMergeSha({ owner, repo, number }) {
+ const env = { ...process.env };
+ if (process.env.CROSS_REPO_TOKEN) env.GH_TOKEN = process.env.CROSS_REPO_TOKEN;
+ let out;
+ try {
+ out = execFileSync('gh', ['api', `repos/${owner}/${repo}/pulls/${number}`, '--jq', '.merged_at,.merge_commit_sha'], {
+ encoding: 'utf8',
+ env,
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ } catch (err) {
+ const stderr = String(err?.stderr || '');
+ // A deleted or never-visible PR is an answer; anything else is infra.
+ if (/HTTP 404/i.test(stderr)) return null;
+ throw new Error(`gh api repos/${owner}/${repo}/pulls/${number} failed: ${stderr.trim().slice(0, 200)}`);
+ }
+ const [mergedAt, sha] = out.split('\n').map((s) => s.trim());
+ if (!mergedAt || mergedAt === 'null') return null;
+ return /^[0-9a-f]{40}$/i.test(sha || '') ? sha.toLowerCase() : null;
+}
+
+// Attachments are fetched separately rather than nested three deep. Linear
+// scores query complexity as roughly the product of the page sizes, and
+// releases x issues x attachments in one shot exceeds the cap outright.
+// Every connection carries an explicit page size whose `hasNextPage` is
+// checked, because a silently truncated list would drop a ticket's fix pull
+// request and demote it to a benign-looking skip.
+const RELEASES_QUERY = `query($after:String){
+ releases(first:25, after:$after){
+ pageInfo{ hasNextPage endCursor }
+ nodes{ id name version
+ issues(first:50){ pageInfo{ hasNextPage } nodes{ id identifier } } } } }`;
+
+const ATTACHMENTS_QUERY = `query($ids:[ID!], $after:String){
+ issues(filter:{ id:{ in:$ids } }, first:25, after:$after){
+ pageInfo{ hasNextPage endCursor }
+ nodes{ id attachments(first:50){ pageInfo{ hasNextPage } nodes{ url } } } } }`;
+
+async function fetchAttachments(issueIds) {
+ const byIssue = new Map();
+ for (let i = 0; i < issueIds.length; i += 25) {
+ const ids = issueIds.slice(i, i + 25);
+ let after = null;
+ for (;;) {
+ const page = (await linear(ATTACHMENTS_QUERY, { ids, after })).issues;
+ for (const n of page.nodes) {
+ if (n.attachments.pageInfo.hasNextPage) {
+ throw new Error(`issue ${n.id} has more attachments than one page; paginate before trusting this run`);
+ }
+ byIssue.set(n.id, n.attachments.nodes.map((a) => a.url));
+ }
+ if (!page.pageInfo.hasNextPage) break;
+ after = page.pageInfo.endCursor;
+ }
+ }
+ return byIssue;
+}
+
+async function fetchPipeline() {
+ const releases = [];
+ let after = null;
+ for (;;) {
+ const page = (await linear(RELEASES_QUERY, { after })).releases;
+ releases.push(...page.nodes);
+ if (!page.pageInfo.hasNextPage) break;
+ after = page.pageInfo.endCursor;
+ }
+
+ for (const r of releases) {
+ if (r.issues.pageInfo.hasNextPage) {
+ throw new Error(`release ${r.name} has more issues than one page; paginate before trusting this run`);
+ }
+ }
+
+ const issueIds = [...new Set(releases.flatMap((r) => r.issues.nodes.map((i) => i.id)))];
+ const attachmentsByIssue = await fetchAttachments(issueIds);
+ const releaseByVersion = new Map(releases.map((r) => [String(r.version), r]));
+ const tickets = new Map();
+ for (const r of releases) {
+ for (const i of r.issues.nodes) {
+ const t = tickets.get(i.identifier) ?? {
+ id: i.id,
+ identifier: i.identifier,
+ prs: [
+ ...new Set((attachmentsByIssue.get(i.id) ?? []).filter((u) => PRIVATE_PR_RE.test(u ?? ''))),
+ ],
+ attachedReleases: [],
+ };
+ t.attachedReleases.push(r);
+ tickets.set(i.identifier, t);
+ }
+ }
+ return { releaseByVersion, tickets: [...tickets.values()] };
+}
+
+/**
+ * Earliest stable tag containing any of a ticket's fix commits, plus how much
+ * we actually know.
+ *
+ * `not-mirrored` from the resolver means the commit was never located, so it
+ * contributes NO evidence — only a `not-in-any-stable` verdict, which required
+ * finding the commit and walking every tag, can justify withdrawing a stamp.
+ */
+function resolveTicket(ticket, stableTags, rank) {
+ let best = null;
+ let provenNotShipped = false;
+ for (const url of ticket.prs) {
+ const m = PRIVATE_PR_RE.exec(url);
+ if (!m) continue;
+ const [owner, repo] = [m[1], m[2]];
+ if (`${owner}/${repo}` !== PRIVATE_REPO) continue;
+ const sha = prMergeSha({ owner, repo, number: Number(m[3]) });
+ if (!sha) continue;
+ const r = resolveShippedVersion({
+ privateSha: sha,
+ stableTags,
+ findMirroredCommits: realFindMirroredCommits,
+ contains: realContains,
+ });
+ if (r.shipped) {
+ if (best === null || rank.get(r.tag) < rank.get(best)) best = r.tag;
+ } else if (r.reason === 'not-in-any-stable') {
+ provenNotShipped = true;
+ }
+ }
+ if (best) return { evidence: 'shipped', shippedTag: best };
+ if (provenNotShipped) return { evidence: 'proven-not-shipped', shippedTag: null };
+ return { evidence: 'unresolvable', shippedTag: null };
+}
+
+async function main() {
+ const live = process.env.STAMP_MODE === 'live';
+ if (!process.env.LINEAR_API_KEY) {
+ log('::notice::LINEAR_API_KEY is not set - nothing to reconcile.');
+ return;
+ }
+
+ const stableTags = realStableTags();
+ const sorted = stableTags.filter((t) => /^v\d+\.\d+\.\d+$/.test(t.trim())).map((t) => t.trim());
+ const rank = new Map(sorted.map((t, i) => [t, i]));
+
+ const { releaseByVersion, tickets } = await fetchPipeline();
+ log(`Considering ${tickets.length} ticket(s) across ${releaseByVersion.size} release(s).`);
+
+ const plans = [];
+ for (const ticket of tickets) {
+ const { evidence, shippedTag } = resolveTicket(ticket, stableTags, rank);
+ const plan = planTicketReconciliation({
+ attachedReleases: ticket.attachedReleases,
+ shippedTag,
+ evidence,
+ releaseByVersion,
+ });
+ plans.push({ ticket, plan });
+ }
+
+ for (const { ticket, plan } of plans) {
+ if (plan.action === 'noop') continue;
+ const attached = ticket.attachedReleases.map((r) => r.name).join(', ');
+ log(`${live ? 'APPLY' : 'DRY '} ${ticket.identifier}: ${plan.action} (${plan.reason}) [was: ${attached}]`);
+ if (!live || (plan.add.length === 0 && plan.remove.length === 0)) continue;
+ await linear(
+ `mutation($id:String!,$in:IssueUpdateInput!){ issueUpdate(id:$id,input:$in){ success } }`,
+ { id: ticket.id, in: { addedReleaseIds: plan.add, removedReleaseIds: plan.remove } },
+ );
+ }
+
+ const counts = summarize(plans);
+ log(
+ `${live ? 'Applied' : 'Dry run'}: ${counts.attach} attach, ${counts.reattach} reattach, ` +
+ `${counts.skip} skipped, ${counts.noop} already correct.`,
+ );
+ if (!live) log('Set STAMP_MODE=live to apply.');
+ console.log(JSON.stringify({ live, counts }));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ main().catch((err) => {
+ console.error(`::error::stamp-by-containment: ${err.message}`);
+ process.exit(1);
+ });
+}
diff --git a/.github/scripts/stamp-by-containment.test.mjs b/.github/scripts/stamp-by-containment.test.mjs
new file mode 100644
index 000000000..6198bf7f4
--- /dev/null
+++ b/.github/scripts/stamp-by-containment.test.mjs
@@ -0,0 +1,169 @@
+import { describe, expect, test } from 'vitest';
+import {
+ isBetaRelease,
+ planTicketReconciliation,
+ summarize,
+} from './stamp-by-containment.mjs';
+
+const rel = (id, version) => ({ id, name: `v${version}`, version });
+
+const R = {
+ '0.35.1': rel('r-0351', '0.35.1'),
+ '0.35.6': rel('r-0356', '0.35.6'),
+ '0.36.0': rel('r-0360', '0.36.0'),
+ '0.42.0': rel('r-0420', '0.42.0'),
+ '0.43.0': rel('r-0430', '0.43.0'),
+ '0.45.3': rel('r-0453', '0.45.3'),
+ '0.46.0': rel('r-0460', '0.46.0'),
+ '0.46.1': rel('r-0461', '0.46.1'),
+ '0.46.0-beta.35': rel('r-b35', '0.46.0-beta.35'),
+ '0.47.0-beta.5': rel('r-b5', '0.47.0-beta.5'),
+};
+const byVersion = new Map(Object.entries(R));
+
+const plan = (args) => planTicketReconciliation({ releaseByVersion: byVersion, ...args });
+
+describe('isBetaRelease', () => {
+ test.each([
+ ['0.46.0-beta.35', true],
+ ['0.47.0-beta.5', true],
+ ['0.46.0', false],
+ ['0.45.3', false],
+ ])('%s -> beta=%s', (version, expected) => {
+ expect(isBetaRelease({ version })).toBe(expected);
+ });
+
+ test('a missing version is not treated as a beta', () => {
+ // Guessing "beta" for an unknown shape would make the reconciler skip a
+ // stable it should have corrected.
+ expect(isBetaRelease({})).toBe(false);
+ expect(isBetaRelease(null)).toBe(false);
+ });
+});
+
+describe('planTicketReconciliation', () => {
+ test('an unresolvable fix commit is never acted on', () => {
+ // Removing a stamp we cannot verify would destroy a possibly-correct edit.
+ const p = plan({
+ attachedReleases: [R['0.46.0']],
+ shippedTag: null,
+ evidence: 'unresolvable',
+ });
+ expect(p).toMatchObject({ action: 'skip', add: [], remove: [] });
+ });
+
+ test('an already-correct ticket is a noop', () => {
+ expect(
+ plan({ attachedReleases: [R['0.36.0']], shippedTag: 'v0.36.0', evidence: 'shipped' }).action,
+ ).toBe('noop');
+ });
+
+ test('a ticket stamped ~10 releases late is moved to the earliest container', () => {
+ const p = plan({
+ attachedReleases: [R['0.46.0']],
+ shippedTag: 'v0.36.0',
+ evidence: 'shipped',
+ });
+ expect(p.action).toBe('attach');
+ expect(p.add).toEqual([R['0.36.0'].id]);
+ expect(p.remove).toEqual([R['0.46.0'].id]);
+ });
+
+ test('a spurious extra stable is dropped while the correct one is kept', () => {
+ const p = plan({
+ attachedReleases: [R['0.35.1'], R['0.35.6']],
+ shippedTag: 'v0.35.6',
+ evidence: 'shipped',
+ });
+ expect(p.action).toBe('reattach');
+ expect(p.add).toEqual([]);
+ expect(p.remove).toEqual([R['0.35.1'].id]);
+ });
+
+ test('an accumulator artifact is dropped without disturbing the real stamp', () => {
+ const p = plan({
+ attachedReleases: [R['0.45.3'], R['0.46.0']],
+ shippedTag: 'v0.45.3',
+ evidence: 'shipped',
+ });
+ expect(p.remove).toEqual([R['0.46.0'].id]);
+ expect(p.add).toEqual([]);
+ });
+
+ test('BETA attachments are never touched', () => {
+ // A beta is a correct per-cut delta; only the stable is containment-derived.
+ const p = plan({
+ attachedReleases: [R['0.46.0-beta.35'], R['0.46.0']],
+ shippedTag: 'v0.46.1',
+ evidence: 'shipped',
+ });
+ expect(p.add).toEqual([R['0.46.1'].id]);
+ expect(p.remove).toEqual([R['0.46.0'].id]);
+ expect(p.remove).not.toContain(R['0.46.0-beta.35'].id);
+ });
+
+ test('a beta-only ticket whose fix is not yet in a stable stays untouched', () => {
+ const p = plan({
+ attachedReleases: [R['0.47.0-beta.5']],
+ shippedTag: null,
+ evidence: 'proven-not-shipped',
+ });
+ expect(p).toMatchObject({ action: 'noop', add: [], remove: [], reason: 'not-in-any-stable' });
+ });
+
+ test('a stable stamp is withdrawn when the fix is PROVABLY not in any stable', () => {
+ const p = plan({
+ attachedReleases: [R['0.46.0'], R['0.47.0-beta.5']],
+ shippedTag: null,
+ evidence: 'proven-not-shipped',
+ });
+ expect(p.action).toBe('reattach');
+ expect(p.remove).toEqual([R['0.46.0'].id]);
+ expect(p.add).toEqual([]);
+ });
+
+ test('an UNRESOLVABLE fix commit never strips a stable, unlike a proven one', () => {
+ // The distinction the two branches turn on. `not-mirrored` from the
+ // resolver means the commit was never located; it looks identical to
+ // "not shipped" if you only read a boolean, and collapsing them would
+ // delete correct stamps on tickets whose PR link is a merge-queue
+ // artifact, a revert, or predates the mirror.
+ const attachedReleases = [R['0.46.0'], R['0.47.0-beta.5']];
+ const proven = plan({ attachedReleases, shippedTag: null, evidence: 'proven-not-shipped' });
+ const unknown = plan({ attachedReleases, shippedTag: null, evidence: 'unresolvable' });
+
+ expect(proven.remove).toEqual([R['0.46.0'].id]);
+ expect(unknown.remove).toEqual([]);
+ expect(unknown.action).toBe('skip');
+ });
+
+ test('a containing stable with no release object is reported, not invented', () => {
+ // Minting releases belongs to the cut, not to this reconciler.
+ const p = plan({
+ attachedReleases: [R['0.46.0']],
+ shippedTag: 'v0.99.9',
+ evidence: 'shipped',
+ });
+ expect(p.action).toBe('skip');
+ expect(p.reason).toBe('no-release-object:0.99.9');
+ expect(p.remove).toEqual([]);
+ });
+
+ test('a ticket with no attachments at all gets the correct stable attached', () => {
+ const p = plan({ attachedReleases: [], shippedTag: 'v0.43.0', evidence: 'shipped' });
+ expect(p).toMatchObject({ action: 'attach', add: [R['0.43.0'].id], remove: [] });
+ });
+});
+
+describe('summarize', () => {
+ test('counts every action kind', () => {
+ const plans = [
+ { plan: { action: 'noop' } },
+ { plan: { action: 'attach' } },
+ { plan: { action: 'attach' } },
+ { plan: { action: 'reattach' } },
+ { plan: { action: 'skip' } },
+ ];
+ expect(summarize(plans)).toEqual({ noop: 1, attach: 2, reattach: 1, skip: 1 });
+ });
+});
diff --git a/.github/workflows/linear-release.yml b/.github/workflows/linear-release.yml
index 9fef40f02..67a44fbe3 100644
--- a/.github/workflows/linear-release.yml
+++ b/.github/workflows/linear-release.yml
@@ -44,6 +44,20 @@ name: Linear Release
# moved. Keying on it attributed tickets to versions that never carried them,
# always in the same direction (too early). A tag's own name cannot be wrong.
#
+# STABLE ATTRIBUTION IS CONTAINMENT, NOT SCAN RANGE
+# The CLI's sync answers "which pull requests fall in this cut's scan range".
+# That is right for a beta, which genuinely reports what is new in it, and
+# wrong for a stable, where the useful fact is the earliest build a user can
+# install to get the fix. So on a stable cut a second pass recomputes the
+# STABLE attachment by tag containment and corrects it; betas are never
+# touched. It refuses rather than guesses: a ticket whose fix commit cannot be
+# resolved keeps whatever it had. Ships in dry-run until the STAMP_MODE repo
+# variable is set to `live`.
+#
+# Running this workflow by hand against any stable tag re-runs that pass over
+# the whole pipeline, which is also how a backfill of historical stamps is
+# performed — the pass is not scoped to the dispatching tag.
+#
# COMMIT SCAN RANGE
# The lower bound depends on the channel, because the two releases answer
# different questions:
@@ -184,3 +198,46 @@ jobs:
access_key: ${{ secrets.LINEAR_ACCESS_KEY }}
command: complete
version: ${{ steps.derive.outputs.version }}
+
+ # The sync above attributes by scan range, which is the right answer for a
+ # beta ("what is new here") and the wrong one for a stable, where the
+ # useful fact is the earliest build carrying the fix. This pass recomputes
+ # the STABLE attachment by tag containment and corrects it. Betas are left
+ # alone. Reads the fix pull requests out of the private monorepo, which
+ # this repo's own token cannot see, hence the bridge App.
+ - name: Check whether the bridge App is configured
+ if: steps.derive.outputs.channel == 'stable'
+ id: bridge-check
+ env:
+ OK_RELEASE_BRIDGE_APP_ID: ${{ secrets.OK_RELEASE_BRIDGE_APP_ID }}
+ run: |
+ set -euo pipefail
+ if [[ -n "${OK_RELEASE_BRIDGE_APP_ID:-}" ]]; then
+ echo "configured=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "configured=false" >> "$GITHUB_OUTPUT"
+ echo "::warning::OK_RELEASE_BRIDGE_APP_ID not set — fix commits cannot be resolved, so every ticket will be skipped rather than mis-stamped."
+ fi
+
+ - name: Mint cross-repo read token (bridge App)
+ if: steps.derive.outputs.channel == 'stable' && steps.bridge-check.outputs.configured == 'true'
+ id: bridge-token
+ uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+ with:
+ # Public client ID for inkeep-ok-release-bridge (non-secret).
+ client-id: Iv23lii4qS2FAc6tkzfI
+ private-key: ${{ secrets.OK_RELEASE_BRIDGE_APP_PRIVATE_KEY }}
+ owner: inkeep
+ repositories: agents-private
+ permission-contents: read
+ permission-pull-requests: read
+
+ - name: Correct the stable stamp by containment
+ if: steps.derive.outputs.channel == 'stable'
+ env:
+ LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
+ CROSS_REPO_TOKEN: ${{ steps.bridge-token.outputs.token }}
+ # Absent by default, so wiring credentials cannot by itself start
+ # rewriting tickets. Set to `live` on the repo to arm real writes.
+ STAMP_MODE: ${{ vars.STAMP_MODE }}
+ run: node .github/scripts/stamp-by-containment.mjs