Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Close the report-to-shipped loop: origin link, fan-in gate, reporter write-back (#2967)

Andrew Mikofalvy240e66abf4a3
diff --git a/.github/scripts/write-back-gate.mjs b/.github/scripts/write-back-gate.mjs
new file mode 100644
index 000000000..18c8ffe71
--- /dev/null
+++ b/.github/scripts/write-back-gate.mjs
@@ -0,0 +1,339 @@
+/**
+ * The decisions behind telling a bug reporter their fix shipped: which of a
+ * ticket's attachments is a place a human can be replied to, and whether
+ * everything that descended from their report has actually gone out.
+ *
+ * Why this file does no IO at all. The two failure modes that matter here are
+ * both silent-and-public: replying in the wrong place, and telling someone a
+ * fix is out while part of what they reported is still open. Neither is caught
+ * by watching a workflow go green, so the decisions have to be cheap enough to
+ * test exhaustively, which means no Linear client, no fetch, no git, no clock.
+ * The sibling `write-back.mjs` owns every boundary and imports this.
+ *
+ * ATTACHMENT CLASSIFICATION. A Linear ticket's attachments are a mixed bag: the
+ * report's origin, the PRs and commits that fixed it, uploaded diagnostic
+ * bundles, and links to wherever it was discussed. Confusing a fix reference
+ * for an origin is how a bot ends up replying to its own pull request, so
+ * GitHub pull and commit URLs are classified as fix references and can never
+ * become origins no matter what else is missing.
+ *
+ * THE FAN-IN GATE. A single report routinely fans into several tickets. Telling
+ * the reporter "fixed in v0.36.0" while one of those is still open is worse
+ * than staying quiet, because it reads as a claim that everything they raised
+ * is handled. So the gate blocks on EVERY non-canceled descendant, not only the
+ * Bug-labelled ones: on the live tree this was designed against, two of six
+ * children carry no labels at all, and one of those is still open. Gating on
+ * the label would have made it invisible. Unlabelled descendants are reported
+ * separately so the triage gap stays visible rather than being quietly
+ * absorbed.
+ *
+ * Failing safe here means silence, never a false claim.
+ */
+
+const GITHUB_ISSUE_RE = /^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)(?:[/?#].*)?$/i;
+const GITHUB_PULL_RE = /^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)(?:[/?#].*)?$/i;
+const GITHUB_COMMIT_RE = /^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/]+)\/commit\/([0-9a-f]{7,40})(?:[/?#].*)?$/i;
+// Discord permalinks carry guild/channel[/message]; the channel segment is the
+// forum thread's own id, which is what a reply is addressed to.
+const DISCORD_THREAD_RE =
+ /^https?:\/\/(?:(?:canary|ptb)\.)?discord(?:app)?\.com\/channels\/(\d+|@me)\/(\d+)(?:\/(\d+))?(?:[/?#].*)?$/i;
+const SLACK_ARCHIVE_RE = /^https?:\/\/[^/]*\.slack\.com\/archives\//i;
+const LINEAR_UPLOAD_RE = /^https?:\/\/uploads\.linear\.app\//i;
+
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)$/;
+
+const RELEASES_URL = 'https://github.com/inkeep/open-knowledge/releases';
+// Discord caps a message at 2000 characters. Bounding the quoted prose leaves
+// room for the surrounding lines on either channel and keeps a pathological
+// changeset from turning the reply into a wall.
+const MAX_PROSE_CHARS = 1200;
+
+/**
+ * What a single attachment URL is, for write-back purposes.
+ *
+ * { kind: 'repliable-origin', channel: 'github-issue' | 'discord-thread', ... }
+ * { kind: 'unrepliable-origin', channel: 'slack-archive' | 'linear-upload' }
+ * { kind: 'fix-reference', channel: 'pull-request' | 'commit' }
+ * { kind: 'unknown' }
+ *
+ * `unrepliable-origin` exists as its own answer rather than collapsing into
+ * `unknown` so the caller can say WHY it skipped. A Slack archive link and a
+ * diagnostic bundle both name a real report; there is simply nowhere in them to
+ * post a reply, and that is worth a warning rather than silence.
+ */
+export function classifyAttachment(rawUrl) {
+ const url = String(rawUrl ?? '').trim();
+ if (!url) return { kind: 'unknown', url };
+
+ // Fix references are matched before origins on purpose: a pull request lives
+ // on github.com just like an issue does, and reading one as a place to reply
+ // would post the notification onto the fix instead of onto the report.
+ const pull = GITHUB_PULL_RE.exec(url);
+ if (pull) {
+ return {
+ kind: 'fix-reference',
+ channel: 'pull-request',
+ url,
+ owner: pull[1],
+ repo: pull[2],
+ number: Number(pull[3]),
+ };
+ }
+
+ const commit = GITHUB_COMMIT_RE.exec(url);
+ if (commit) {
+ return {
+ kind: 'fix-reference',
+ channel: 'commit',
+ url,
+ owner: commit[1],
+ repo: commit[2],
+ sha: commit[3].toLowerCase(),
+ };
+ }
+
+ const issue = GITHUB_ISSUE_RE.exec(url);
+ if (issue) {
+ return {
+ kind: 'repliable-origin',
+ channel: 'github-issue',
+ url,
+ owner: issue[1],
+ repo: issue[2],
+ number: Number(issue[3]),
+ };
+ }
+
+ const discord = DISCORD_THREAD_RE.exec(url);
+ if (discord) {
+ return { kind: 'repliable-origin', channel: 'discord-thread', url, threadId: discord[2] };
+ }
+
+ if (SLACK_ARCHIVE_RE.test(url)) {
+ return { kind: 'unrepliable-origin', channel: 'slack-archive', url };
+ }
+ if (LINEAR_UPLOAD_RE.test(url)) {
+ return { kind: 'unrepliable-origin', channel: 'linear-upload', url };
+ }
+
+ return { kind: 'unknown', url };
+}
+
+/**
+ * Split a ticket's attachments into the three buckets the write-back needs.
+ * Returns { origins, unrepliable, fixReferences } with the classification
+ * objects, in attachment order.
+ *
+ * `fixReferences` keeps pull requests ahead of commits: a pull request resolves
+ * to a merge commit whose mirrored copy is what tag containment walks, while a
+ * bare commit URL may be one of many on a single ticket. Both shapes occur in
+ * practice, so neither is treated as the only one.
+ */
+export function partitionAttachments(attachmentUrls = []) {
+ const origins = [];
+ const unrepliable = [];
+ const pulls = [];
+ const commits = [];
+
+ for (const raw of attachmentUrls) {
+ const classified = classifyAttachment(raw);
+ if (classified.kind === 'repliable-origin') origins.push(classified);
+ else if (classified.kind === 'unrepliable-origin') unrepliable.push(classified);
+ else if (classified.kind === 'fix-reference') {
+ (classified.channel === 'pull-request' ? pulls : commits).push(classified);
+ }
+ }
+
+ return { origins, unrepliable, fixReferences: [...pulls, ...commits] };
+}
+
+/** Numeric semver ordering. String comparison puts v0.9.0 above v0.36.0. */
+export function compareVersions(a, b) {
+ const pa = SEMVER_RE.exec(String(a ?? '').trim());
+ const pb = SEMVER_RE.exec(String(b ?? '').trim());
+ if (!pa) throw new Error(`not a version: '${a}'`);
+ if (!pb) throw new Error(`not a version: '${b}'`);
+ for (let i = 1; i <= 3; i += 1) {
+ const diff = Number(pa[i]) - Number(pb[i]);
+ if (diff !== 0) return diff;
+ }
+ return 0;
+}
+
+/** Highest of a non-empty version list, normalized without the leading `v`. */
+export function highestVersion(versions) {
+ let best = null;
+ for (const version of versions) {
+ if (best === null || compareVersions(version, best) > 0) best = version;
+ }
+ return best === null ? null : String(best).trim().replace(/^v/, '');
+}
+
+/**
+ * Decide whether everything descending from a report has shipped.
+ *
+ * Inputs:
+ * ticket { identifier, stateType, labels? }
+ * descendants [ same shape ]
+ * resolveVersion(node) -> version string | null (injected; null means
+ * "could not be derived", which is a reason to withhold, never
+ * a reason to assume it shipped)
+ * log injected annotation sink
+ *
+ * A ticket that has children is the report; its own state tracks triage rather
+ * than a ship event, so the decision is made over its descendants. A ticket
+ * with no children is evaluated alone, which is the common single-fix case.
+ *
+ * Three-way per node:
+ * shipped completed and a version resolves contributes its version
+ * neutral canceled (won't-fix or duplicate) contributes nothing, blocks nothing
+ * blocking anything else withholds
+ *
+ * Returns { decision, version, coverage, blocking, unresolved, neutral,
+ * unlabelledDescendants }. `unresolved` is the subset of `blocking` that is
+ * completed but whose version could not be derived: routine "still open" and
+ * "we could not work out where this went" deserve different annotations, and
+ * the second one means something is wrong with the fix-reference chain.
+ */
+export function evaluateFanIn({ ticket, descendants = [], resolveVersion, log = () => {} }) {
+ if (!ticket?.identifier) throw new Error('evaluateFanIn needs a ticket with an identifier');
+ if (typeof resolveVersion !== 'function') throw new Error('evaluateFanIn needs a resolveVersion function');
+
+ const considered = descendants.length > 0 ? descendants : [ticket];
+
+ const coverage = [];
+ const versions = [];
+ const blocking = [];
+ const unresolved = [];
+ const neutral = [];
+ const unlabelledDescendants = [];
+
+ for (const node of considered) {
+ if (descendants.length > 0 && (node.labels ?? []).length === 0) {
+ unlabelledDescendants.push(node.identifier);
+ }
+
+ if (node.stateType === 'canceled') {
+ neutral.push(node.identifier);
+ continue;
+ }
+ if (node.stateType !== 'completed') {
+ blocking.push(node.identifier);
+ continue;
+ }
+
+ const version = resolveVersion(node);
+ if (!version) {
+ // Completed but unlocatable. Refusing here is the whole point of the
+ // gate: naming a version we could not derive is the one outcome worse
+ // than saying nothing.
+ blocking.push(node.identifier);
+ unresolved.push(node.identifier);
+ continue;
+ }
+ coverage.push(node.identifier);
+ versions.push(version);
+ }
+
+ coverage.sort();
+ blocking.sort();
+ unresolved.sort();
+
+ if (unlabelledDescendants.length > 0) {
+ log(
+ `::notice::write-back: ${ticket.identifier} has descendants with no labels (${unlabelledDescendants.join(', ')}); ` +
+ 'they are gated on anyway, but the triage gap is worth closing.',
+ );
+ }
+
+ if (blocking.length > 0 || coverage.length === 0) {
+ const reason =
+ blocking.length > 0
+ ? `outstanding: ${blocking.join(', ')}`
+ : 'nothing descending from it has shipped';
+ log(`::notice::write-back: withholding on ${ticket.identifier} (${reason}).`);
+ return {
+ decision: 'withhold',
+ version: null,
+ coverage,
+ blocking,
+ unresolved,
+ neutral,
+ unlabelledDescendants,
+ };
+ }
+
+ return {
+ decision: 'notify',
+ version: highestVersion(versions),
+ coverage,
+ blocking,
+ unresolved,
+ neutral,
+ unlabelledDescendants,
+ };
+}
+
+/**
+ * The reply a reporter actually reads.
+ *
+ * The signature is the redaction mechanism. Everything a reporter should never
+ * see lives on the Linear ticket: its internal title, its assignee, the
+ * customer it was raised for, notes about work that has not shipped. None of
+ * that is a parameter here, so no amount of downstream carelessness can leak
+ * it. What can reach the reply is the changeset prose, which is written for the
+ * public release notes and is already published, plus the derived version and
+ * the ticket identifiers the reporter's own report fanned into. Widening these
+ * parameters is the one change to this file that needs a second look.
+ *
+ * The coverage line is not decoration. A report that fanned into three tickets
+ * gets one reply, and without the list the reporter has no way to tell whether
+ * the other two were handled or quietly dropped.
+ *
+ * Returns the reply text, or null when there is nothing truthful to say. An
+ * empty changeset is the one case: a blank or version-only reply reads as a
+ * claim with no content behind it, so the caller warns and posts nothing.
+ */
+export function composeReply({ changeset = {}, version, originChannel, coverage = [] }) {
+ const normalizedVersion = String(version ?? '')
+ .trim()
+ .replace(/^v/, '');
+ if (!SEMVER_RE.test(normalizedVersion)) {
+ throw new Error(`composeReply needs a derived version, got '${version}'`);
+ }
+
+ const body = String(changeset.body ?? '').trim();
+ const title = String(changeset.title ?? '').trim();
+ const prose = body || title;
+ if (!prose) return null;
+
+ const trimmedProse =
+ prose.length > MAX_PROSE_CHARS ? `${prose.slice(0, MAX_PROSE_CHARS).trimEnd()}...` : prose;
+
+ const lines = [
+ `This shipped in Open Knowledge v${normalizedVersion}. Thanks for the report.`,
+ '',
+ trimmedProse,
+ ];
+
+ if (coverage.length > 0) {
+ lines.push('', `Covers ${[...coverage].sort().join(', ')}.`);
+ }
+
+ lines.push('', updateInstruction(originChannel, normalizedVersion));
+
+ return lines.join('\n');
+}
+
+/**
+ * Both channels render markdown, so the difference is the link form: GitHub
+ * renders an inline link, while a bare URL on Discord expands into an embed
+ * card unless it is wrapped in angle brackets.
+ */
+function updateInstruction(originChannel, version) {
+ const upgrade = `\`npm install -g @inkeep/open-knowledge@${version}\``;
+ if (originChannel === 'discord-thread') {
+ return `To pick it up, run ${upgrade}, or download the latest desktop build from <${RELEASES_URL}>.`;
+ }
+ return `To pick it up, run ${upgrade}, or download the latest desktop build from [the releases page](${RELEASES_URL}).`;
+}
diff --git a/.github/scripts/write-back-gate.test.mjs b/.github/scripts/write-back-gate.test.mjs
new file mode 100644
index 000000000..be6bd95e7
--- /dev/null
+++ b/.github/scripts/write-back-gate.test.mjs
@@ -0,0 +1,367 @@
+import { describe, expect, test } from 'vitest';
+import {
+ classifyAttachment,
+ compareVersions,
+ composeReply,
+ evaluateFanIn,
+ highestVersion,
+ partitionAttachments,
+} from './write-back-gate.mjs';
+
+// Attachment shapes taken off live tickets rather than invented: PRD-7539 (a
+// fix PR plus a GitHub issue origin), PRD-7394 (nothing but an uploaded
+// diagnostic bundle), PRD-7399 (seven commit URLs and no PR at all), and
+// PRD-7490 (a fix PR, a Discord thread, and a Slack archive link).
+const GH_ISSUE = 'https://github.com/inkeep/open-knowledge/issues/769';
+const GH_PULL = 'https://github.com/inkeep/agents-private/pull/2844';
+const GH_COMMIT = 'https://github.com/inkeep/agents-private/commit/da71f0c698ccaac11da915169ca6c7d585d5eb97';
+const DISCORD_THREAD = 'https://discord.com/channels/1234567890/9876543210/1122334455';
+const SLACK_ARCHIVE = 'https://inkeep.slack.com/archives/C016VCYCL74/p1727122965001469';
+const LINEAR_UPLOAD = 'https://uploads.linear.app/abc/def/diagnostics.zip';
+
+describe('attachment classification', () => {
+ test('a GitHub issue is a repliable origin', () => {
+ const c = classifyAttachment(GH_ISSUE);
+ expect(c.kind).toBe('repliable-origin');
+ expect(c.channel).toBe('github-issue');
+ expect(c).toMatchObject({ owner: 'inkeep', repo: 'open-knowledge', number: 769 });
+ });
+
+ test('a Discord thread permalink is a repliable origin carrying the thread id', () => {
+ const c = classifyAttachment(DISCORD_THREAD);
+ expect(c.kind).toBe('repliable-origin');
+ expect(c.channel).toBe('discord-thread');
+ expect(c.threadId).toBe('9876543210');
+ });
+
+ test('a Discord permalink with no message segment still yields the thread', () => {
+ const c = classifyAttachment('https://discord.com/channels/1234567890/9876543210');
+ expect(c.channel).toBe('discord-thread');
+ expect(c.threadId).toBe('9876543210');
+ });
+
+ test('a Slack archive link is an origin with nowhere to reply, so the caller can skip and warn', () => {
+ const c = classifyAttachment(SLACK_ARCHIVE);
+ expect(c.kind).toBe('unrepliable-origin');
+ expect(c.channel).toBe('slack-archive');
+ });
+
+ test('a Linear diagnostic bundle is an origin with nowhere to reply', () => {
+ const c = classifyAttachment(LINEAR_UPLOAD);
+ expect(c.kind).toBe('unrepliable-origin');
+ expect(c.channel).toBe('linear-upload');
+ });
+
+ test('a GitHub pull request is a fix reference and never an origin', () => {
+ const c = classifyAttachment(GH_PULL);
+ expect(c.kind).toBe('fix-reference');
+ expect(c.channel).toBe('pull-request');
+ expect(c.number).toBe(2844);
+ });
+
+ test('a GitHub commit is a fix reference and never an origin', () => {
+ const c = classifyAttachment(GH_COMMIT);
+ expect(c.kind).toBe('fix-reference');
+ expect(c.channel).toBe('commit');
+ expect(c.sha).toBe('da71f0c698ccaac11da915169ca6c7d585d5eb97');
+ });
+
+ test('an unrecognized link is unknown rather than guessed at', () => {
+ expect(classifyAttachment('https://example.com/whatever').kind).toBe('unknown');
+ expect(classifyAttachment('').kind).toBe('unknown');
+ expect(classifyAttachment(null).kind).toBe('unknown');
+ });
+
+ test('a ticket carrying only fix-side links produces no origin at all', () => {
+ const { origins, fixReferences } = partitionAttachments([GH_PULL, GH_COMMIT]);
+ expect(origins).toEqual([]);
+ expect(fixReferences.map((f) => f.channel)).toEqual(['pull-request', 'commit']);
+ });
+
+ test('a ticket carrying only commit attachments still yields a usable fix reference', () => {
+ const commits = Array.from(
+ { length: 7 },
+ (_, i) => `https://github.com/inkeep/agents-private/commit/${String(i + 1).repeat(40)}`,
+ );
+ const { fixReferences } = partitionAttachments(commits);
+ expect(fixReferences.length).toBe(7);
+ expect(fixReferences[0].channel).toBe('commit');
+ });
+
+ test('pull requests sort ahead of commits so the merge-commit hop is preferred', () => {
+ const { fixReferences } = partitionAttachments([GH_COMMIT, GH_PULL]);
+ expect(fixReferences.map((f) => f.channel)).toEqual(['pull-request', 'commit']);
+ });
+
+ test('a mixed ticket separates the repliable origin from the unrepliable one', () => {
+ const { origins, unrepliable, fixReferences } = partitionAttachments([
+ GH_PULL,
+ DISCORD_THREAD,
+ SLACK_ARCHIVE,
+ ]);
+ expect(origins.map((o) => o.channel)).toEqual(['discord-thread']);
+ expect(unrepliable.map((o) => o.channel)).toEqual(['slack-archive']);
+ expect(fixReferences.map((f) => f.channel)).toEqual(['pull-request']);
+ });
+});
+
+describe('version ordering', () => {
+ test('versions compare numerically, not as strings', () => {
+ expect(compareVersions('v0.36.0', 'v0.35.2')).toBeGreaterThan(0);
+ expect(compareVersions('0.9.0', '0.36.0')).toBeLessThan(0);
+ expect(compareVersions('v1.0.0', '1.0.0')).toBe(0);
+ });
+
+ test('the highest of a set is returned without its leading v', () => {
+ expect(highestVersion(['v0.35.2', 'v0.36.0', 'v0.35.6'])).toBe('0.36.0');
+ });
+
+ test('a value that is not a version throws rather than sorting arbitrarily', () => {
+ expect(() => compareVersions('latest', '1.0.0')).toThrow(/not a version/);
+ });
+});
+
+describe('fan-in gate', () => {
+ // A map-driven fake keyed by identifier: absent means "no version could be
+ // derived", which the gate must treat as a reason to withhold.
+ const versionsFrom = (map) => (node) => map[node.identifier] ?? null;
+ const node = (identifier, stateType, labels = ['Bug']) => ({ identifier, stateType, labels });
+
+ const evaluate = (overrides) => {
+ const logs = [];
+ const result = evaluateFanIn({ log: (m) => logs.push(m), ...overrides });
+ return { ...result, logs };
+ };
+
+ test('every descendant completed and resolvable notifies with the coverage set', () => {
+ const r = evaluate({
+ ticket: node('PRD-7394', 'started', ['Bug', 'ok:intake']),
+ descendants: [node('PRD-7398', 'completed'), node('PRD-7403', 'completed', [])],
+ resolveVersion: versionsFrom({ 'PRD-7398': 'v0.35.2', 'PRD-7403': 'v0.36.0' }),
+ });
+ expect(r.decision).toBe('notify');
+ expect(r.coverage).toEqual(['PRD-7398', 'PRD-7403']);
+ });
+
+ test('the selected version is the highest contributor by numeric semver', () => {
+ const r = evaluate({
+ ticket: node('PRD-7394', 'started'),
+ descendants: [node('PRD-7398', 'completed'), node('PRD-7403', 'completed')],
+ resolveVersion: versionsFrom({ 'PRD-7398': 'v0.36.0', 'PRD-7403': 'v0.35.2' }),
+ });
+ expect(r.version).toBe('0.36.0');
+ });
+
+ test('an outstanding descendant withholds and is named', () => {
+ const r = evaluate({
+ ticket: node('PRD-7394', 'started'),
+ descendants: [node('PRD-7398', 'completed'), node('PRD-7400', 'unstarted')],
+ resolveVersion: versionsFrom({ 'PRD-7398': 'v0.36.0' }),
+ });
+ expect(r.decision).toBe('withhold');
+ expect(r.blocking).toEqual(['PRD-7400']);
+ expect(r.logs.some((m) => m.includes('PRD-7400'))).toBe(true);
+ });
+
+ test('a ticket with no children is evaluated alone rather than failing', () => {
+ const r = evaluate({
+ ticket: node('PRD-7539', 'completed', ['Bug', 'ok:platform']),
+ descendants: [],
+ resolveVersion: versionsFrom({ 'PRD-7539': 'v0.36.0' }),
+ });
+ expect(r.decision).toBe('notify');
+ expect(r.coverage).toEqual(['PRD-7539']);
+ expect(r.version).toBe('0.36.0');
+ });
+
+ test('a canceled descendant neither blocks nor contributes', () => {
+ const r = evaluate({
+ ticket: node('PRD-7394', 'started'),
+ descendants: [node('PRD-7398', 'completed'), node('PRD-7402', 'canceled')],
+ resolveVersion: versionsFrom({ 'PRD-7398': 'v0.36.0' }),
+ });
+ expect(r.decision).toBe('notify');
+ expect(r.coverage).toEqual(['PRD-7398']);
+ expect(r.neutral).toEqual(['PRD-7402']);
+ });
+
+ test('an open unlabelled descendant withholds, which gating on the Bug label would have missed', () => {
+ // The live PRD-7394 tree: six children, two of them carrying no labels at
+ // all, and one of those two still open.
+ const r = evaluate({
+ ticket: node('PRD-7394', 'started', ['Bug', 'ok:intake']),
+ descendants: [
+ node('PRD-7398', 'completed'),
+ node('PRD-7399', 'completed'),
+ node('PRD-7400', 'completed'),
+ node('PRD-7401', 'unstarted', []),
+ node('PRD-7402', 'completed'),
+ node('PRD-7403', 'completed', []),
+ ],
+ resolveVersion: () => 'v0.36.0',
+ });
+ expect(r.decision).toBe('withhold');
+ expect(r.blocking).toEqual(['PRD-7401']);
+ });
+
+ test('unlabelled descendants are listed so the triage gap is observable rather than silent', () => {
+ const r = evaluate({
+ ticket: node('PRD-7394', 'started'),
+ descendants: [node('PRD-7401', 'unstarted', []), node('PRD-7403', 'completed', [])],
+ resolveVersion: () => 'v0.36.0',
+ });
+ expect(r.unlabelledDescendants).toEqual(['PRD-7401', 'PRD-7403']);
+ expect(r.logs.some((m) => m.startsWith('::notice::') && m.includes('no labels'))).toBe(true);
+ });
+
+ test('a completed descendant whose version cannot be derived withholds rather than assuming it shipped', () => {
+ const r = evaluate({
+ ticket: node('PRD-7394', 'started'),
+ descendants: [node('PRD-7398', 'completed'), node('PRD-7403', 'completed')],
+ resolveVersion: versionsFrom({ 'PRD-7398': 'v0.36.0' }),
+ });
+ expect(r.decision).toBe('withhold');
+ expect(r.blocking).toEqual(['PRD-7403']);
+ // Distinguished from a routine "still open" so the caller can annotate a
+ // broken fix-reference chain differently from ordinary in-progress work.
+ expect(r.unresolved).toEqual(['PRD-7403']);
+ });
+
+ test('an open descendant is blocking but not reported as unresolvable', () => {
+ const r = evaluate({
+ ticket: node('PRD-7394', 'started'),
+ descendants: [node('PRD-7400', 'unstarted')],
+ resolveVersion: () => 'v0.36.0',
+ });
+ expect(r.blocking).toEqual(['PRD-7400']);
+ expect(r.unresolved).toEqual([]);
+ });
+
+ test('a tree whose only descendants are canceled withholds rather than notifying about nothing', () => {
+ const r = evaluate({
+ ticket: node('PRD-7394', 'started'),
+ descendants: [node('PRD-7402', 'canceled')],
+ resolveVersion: () => 'v0.36.0',
+ });
+ expect(r.decision).toBe('withhold');
+ expect(r.coverage).toEqual([]);
+ });
+
+ test('a missing ticket or resolver is a wiring error and throws rather than deciding', () => {
+ expect(() => evaluateFanIn({ ticket: null, resolveVersion: () => null })).toThrow(/identifier/);
+ expect(() => evaluateFanIn({ ticket: { identifier: 'PRD-1' } })).toThrow(/resolveVersion/);
+ });
+});
+
+describe('reply composition', () => {
+ const CHANGESET = {
+ title: 'Honor backslash escapes in the markdown promoters',
+ body: 'Typing `\\==not a highlight\\==` now stays literal instead of turning into a highlight.',
+ };
+
+ const compose = (overrides = {}) =>
+ composeReply({ changeset: CHANGESET, version: 'v0.36.0', originChannel: 'github-issue', ...overrides });
+
+ test('the reply names the version', () => {
+ expect(compose()).toContain('v0.36.0');
+ });
+
+ test('the reply carries the changeset prose', () => {
+ expect(compose()).toContain('stays literal instead of turning into a highlight');
+ });
+
+ test('the reply lists every contributing ticket in sorted order', () => {
+ const text = compose({ coverage: ['PRD-7403', 'PRD-7398', 'PRD-7400'] });
+ expect(text).toContain('Covers PRD-7398, PRD-7400, PRD-7403.');
+ });
+
+ test('a single-ticket report still gets its coverage line', () => {
+ expect(compose({ coverage: ['PRD-7539'] })).toContain('Covers PRD-7539.');
+ });
+
+ test('the update instruction is channel-appropriate', () => {
+ const gh = compose({ originChannel: 'github-issue' });
+ const discord = compose({ originChannel: 'discord-thread' });
+ expect(gh).toContain('[the releases page](https://github.com/inkeep/open-knowledge/releases)');
+ // Bare on Discord it would expand into an embed card; angle brackets suppress that.
+ expect(discord).toContain('<https://github.com/inkeep/open-knowledge/releases>');
+ for (const text of [gh, discord]) {
+ expect(text).toContain('npm install -g @inkeep/[email protected]');
+ }
+ });
+
+ test('an empty changeset body falls back to the changeset title', () => {
+ const text = compose({ changeset: { title: 'Fix the thing', body: ' ' } });
+ expect(text).toContain('Fix the thing');
+ });
+
+ test('an empty body and title refuses to compose rather than emitting a blank reply', () => {
+ expect(compose({ changeset: { title: '', body: '' } })).toBeNull();
+ expect(compose({ changeset: {} })).toBeNull();
+ });
+
+ test('a missing version throws rather than composing a reply that names nothing', () => {
+ expect(() => compose({ version: null })).toThrow(/derived version/);
+ expect(() => compose({ version: 'latest' })).toThrow(/derived version/);
+ });
+
+ test('pathological changeset prose is bounded so the reply fits a Discord message', () => {
+ const text = compose({ changeset: { title: 't', body: 'x'.repeat(5000) }, coverage: ['PRD-1'] });
+ expect(text.length).toBeLessThan(2000);
+ expect(text).toContain('...');
+ });
+
+ test('no internal ticket detail reaches the composed reply', () => {
+ // An adversarial candidate: every field a reporter must never see is
+ // populated with a recognizable value. The composer's parameter list is
+ // the mechanism, so the assertion is that none of it can be threaded in.
+ const candidate = {
+ identifier: 'PRD-7539',
+ title: 'INTERNAL escalation for Contoso, blocked on unreleased auth rewrite',
+ assigneeName: 'Dana Internal',
+ customerName: 'Contoso Corp',
+ unreleasedWorkNote: 'depends on the unshipped v0.40 auth rewrite',
+ changeset: CHANGESET,
+ version: 'v0.36.0',
+ coverage: ['PRD-7539'],
+ originChannel: 'github-issue',
+ };
+
+ const text = composeReply({
+ changeset: candidate.changeset,
+ version: candidate.version,
+ originChannel: candidate.originChannel,
+ coverage: candidate.coverage,
+ });
+
+ for (const secret of [
+ candidate.title,
+ candidate.assigneeName,
+ candidate.customerName,
+ candidate.unreleasedWorkNote,
+ 'INTERNAL',
+ 'Contoso',
+ 'Dana',
+ 'unreleased',
+ 'unshipped',
+ ]) {
+ expect(text).not.toContain(secret);
+ }
+ });
+
+ test('the composer accepts nothing beyond the changeset, the version, the channel, and the coverage', () => {
+ // A regression pin on the redaction mechanism itself: if a future change
+ // widens the parameter object, this states the intended surface out loud.
+ expect(composeReply.length).toBe(1);
+ const text = composeReply({
+ changeset: CHANGESET,
+ version: '0.36.0',
+ originChannel: 'github-issue',
+ coverage: ['PRD-7539'],
+ title: 'INTERNAL leak attempt',
+ assigneeName: 'Dana Internal',
+ });
+ expect(text).not.toContain('INTERNAL');
+ expect(text).not.toContain('Dana');
+ });
+});
diff --git a/.github/scripts/write-back.mjs b/.github/scripts/write-back.mjs
new file mode 100644
index 000000000..3abf8b9ea
--- /dev/null
+++ b/.github/scripts/write-back.mjs
@@ -0,0 +1,562 @@
+#!/usr/bin/env node
+/**
+ * Tell a bug reporter, once, that the fix they reported has shipped.
+ *
+ * Why this enumerates tickets rather than release commits. Every off-the-shelf
+ * release notifier walks the commits in a release, follows each to its pull
+ * request, and reads closing keywords. That returns nothing here: the commits
+ * in this repo arrive through the Copybara mirror and have no pull requests in
+ * the repo the release tags live in. So the walk starts from the other end. Ask
+ * Linear which bug tickets are done, and for each one work forward to the
+ * version it shipped in through tag containment, which the mirror does not
+ * break.
+ *
+ * Why the version is never read from Linear. `linear-release.yml` stamps
+ * releases onto tickets, and it runs off the same dispatch this does. Reading
+ * its output would be a race with an outcome nobody would ever notice: the
+ * reporter is simply told the wrong version. Tag containment depends on nothing
+ * but git, so the two workflows cannot interfere.
+ *
+ * Why dry run is the default, and why the credential alone does not arm it.
+ * Everything downstream of this posts in public under the project's name. An
+ * operator wiring up a Linear key for the back-link half should not thereby
+ * start replying to strangers, so live posting needs a second, explicit opt-in
+ * that does nothing else. Arming steps are in RELEASES.md.
+ *
+ * Usage:
+ * RELEASE_TAG=v0.36.0 node .github/scripts/write-back.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: "nothing to notify about" is a real ANSWER and exits 0.
+ * A missing credential is an answer too. Any infra error (Linear unreachable, a
+ * git failure, a malformed GraphQL response) throws and exits non-zero rather
+ * than being folded into silence, because a caller cannot tell a quiet run from
+ * a broken one and would never look again.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import {
+ parseFixRef,
+ resolvePrivateSha,
+ resolveShippedVersion,
+} from './resolve-shipped-version.mjs';
+import { composeReply, evaluateFanIn, partitionAttachments } from './write-back-gate.mjs';
+
+const LINEAR_GRAPHQL_URL = 'https://api.linear.app/graphql';
+const RELEASES_TAG_BASE = 'https://github.com/inkeep/open-knowledge/releases/tag';
+const DEFAULT_PRIVATE_REPO = 'inkeep/agents-private';
+const FULL_SHA_RE = /^[0-9a-f]{40}$/i;
+const STABLE_TAG_RE = /^v\d+\.\d+\.\d+$/;
+const PAGE_SIZE = 50;
+
+/**
+ * The candidate enumeration.
+ *
+ * `labels: { name: { eq: "Bug" } }` matches when ANY of the ticket's labels is
+ * Bug, which is the intent: a real ticket looks like ["Bug", "ok:platform"].
+ * The sibling form `labels: { every: { name: { eq: "Bug" } } }` reads almost
+ * identically and would silently drop every multi-labelled ticket, which is to
+ * say nearly all of them. The colocated test pins that this query never uses
+ * `every`.
+ *
+ * "Not yet notified" is deliberately absent from the filter. Linear's filter
+ * language has no negative-existence predicate over attachments, and expressing
+ * it as a positive one would invert the meaning; the check runs over the
+ * attachments this query already returns.
+ */
+export const CANDIDATE_QUERY = `
+ query WriteBackCandidates($after: String) {
+ issues(
+ first: ${PAGE_SIZE}
+ after: $after
+ filter: { state: { type: { eq: "completed" } }, labels: { name: { eq: "Bug" } } }
+ ) {
+ pageInfo { hasNextPage endCursor }
+ nodes {
+ id
+ identifier
+ state { type }
+ labels { nodes { name } }
+ attachments { nodes { url } }
+ }
+ }
+ }
+`;
+
+export const CHILDREN_QUERY = `
+ query WriteBackChildren($parentId: ID!, $after: String) {
+ issues(first: ${PAGE_SIZE}, after: $after, filter: { parent: { id: { eq: $parentId } } }) {
+ pageInfo { hasNextPage endCursor }
+ nodes {
+ id
+ identifier
+ state { type }
+ labels { nodes { name } }
+ attachments { nodes { url } }
+ }
+ }
+ }
+`;
+
+/**
+ * The URL that records "this origin has been told about this version".
+ *
+ * Linear treats an attachment URL as an idempotent key against the same issue,
+ * so making this deterministic in (origin, version) buys idempotency with no
+ * read-modify-write and no lock: a second run computes the same URL, finds it
+ * already on the ticket, and posts nothing. It points at the real release page
+ * so a human who clicks it lands somewhere useful.
+ */
+export function notificationMarkerUrl({ version, originUrl }) {
+ const v = String(version ?? '')
+ .trim()
+ .replace(/^v/, '');
+ if (!v) throw new Error('notificationMarkerUrl needs a version');
+ if (!String(originUrl ?? '').trim()) throw new Error('notificationMarkerUrl needs an origin url');
+ return `${RELEASES_TAG_BASE}/v${v}?notified=${encodeURIComponent(originUrl)}`;
+}
+
+/**
+ * The version a ticket's fix is installable in, or null if it is not out yet.
+ *
+ * Across several fix references the answer is the HIGHEST of their individual
+ * first-containing tags: the reporter needs a build that contains all of them,
+ * so the last one to land sets the floor. (Within a single reference,
+ * `resolveShippedVersion` takes the LOWEST across the mirror's copies of that
+ * one commit, which is the opposite question and the opposite answer: a point
+ * release that carried the fix earlier is the one to name.)
+ *
+ * Any reference that has not shipped makes the whole answer null. Part of a fix
+ * being out is not the fix being out.
+ */
+export function deriveVersionForFixRefs({
+ fixReferences = [],
+ stableTags,
+ findMirroredCommits,
+ contains,
+ resolvePrMergeSha,
+ defaultRepo = DEFAULT_PRIVATE_REPO,
+ log = () => {},
+}) {
+ const usable = fixReferences.filter((ref) => ref.channel !== 'commit' || FULL_SHA_RE.test(ref.sha ?? ''));
+ if (usable.length === 0) return null;
+
+ let highest = null;
+ for (const ref of usable) {
+ const parsed = parseFixRef(ref.channel === 'commit' ? ref.sha : ref.url, { defaultRepo });
+ const privateSha = resolvePrivateSha(parsed, { resolvePrMergeSha });
+ const result = resolveShippedVersion({ privateSha, stableTags, findMirroredCommits, contains });
+ if (!result.shipped) {
+ log(`::notice::write-back: ${ref.url} has not reached a stable release yet (${result.reason}).`);
+ return null;
+ }
+ if (highest === null || compareSemver(result.version, highest) > 0) highest = result.version;
+ }
+ return highest;
+}
+
+function compareSemver(a, b) {
+ const pa = a.split('.').map(Number);
+ const pb = b.split('.').map(Number);
+ for (let i = 0; i < 3; i += 1) {
+ if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);
+ }
+ return 0;
+}
+
+/**
+ * Walk every candidate and decide, for each, whether to reply and where.
+ *
+ * Boundaries are injected so the whole decision path is testable with no Linear
+ * account, no git repo, and no network:
+ * listCandidates() -> [candidate]
+ * listChildren(issueId) -> [node]
+ * versionFor(node) -> version | null (tag containment)
+ * readChangesetProse(node) -> { title, body } | null
+ * postReply(origin, text) -> void
+ * recordNotification(marker) -> void
+ *
+ * `live` false is the default and performs zero writes of any kind.
+ *
+ * Returns { posted, skipped, dryRun } where `skipped` carries a reason per
+ * candidate, so a run that did nothing can be read as either "correctly quiet"
+ * or "quietly broken".
+ */
+export async function runWriteBack({
+ listCandidates,
+ listChildren,
+ versionFor,
+ readChangesetProse,
+ postReply,
+ recordNotification,
+ live = false,
+ log = () => {},
+}) {
+ const posted = [];
+ const skipped = [];
+ const skip = (identifier, reason) => skipped.push({ identifier, reason });
+
+ for (const candidate of await listCandidates()) {
+ const { origins, unrepliable, fixReferences } = partitionAttachments(candidate.attachmentUrls ?? []);
+ const children = await listChildren(candidate.id);
+
+ // The version for every node in the tree is resolved up front so the gate
+ // itself stays synchronous and pure.
+ const considered = children.length > 0 ? children : [candidate];
+ const versions = new Map();
+ for (const node of considered) {
+ versions.set(node.identifier, await versionFor(node));
+ }
+
+ const gate = evaluateFanIn({
+ ticket: candidate,
+ descendants: children,
+ resolveVersion: (node) => versions.get(node.identifier) ?? null,
+ log,
+ });
+
+ if (gate.decision !== 'notify') {
+ if (gate.unresolved.length > 0) {
+ log(
+ `::warning::write-back: ${candidate.identifier} is done but no stable release could be derived for ` +
+ `${gate.unresolved.join(', ')}; posting nothing. Check the fix-reference attachments on those tickets.`,
+ );
+ }
+ skip(candidate.identifier, gate.unresolved.length > 0 ? 'version-underivable' : 'fan-in-withheld');
+ continue;
+ }
+
+ if (origins.length === 0) {
+ if (unrepliable.length > 0) {
+ log(
+ `::warning::write-back: ${candidate.identifier} shipped in v${gate.version} but its only origin ` +
+ `(${unrepliable.map((u) => u.channel).join(', ')}) has nowhere to post a reply; posting nothing.`,
+ );
+ skip(candidate.identifier, 'origin-unrepliable');
+ } else {
+ // Not every fix has a reporter. This is the ordinary case, not a fault.
+ skip(candidate.identifier, 'no-origin');
+ }
+ continue;
+ }
+
+ for (const origin of origins) {
+ const marker = notificationMarkerUrl({ version: gate.version, originUrl: origin.url });
+ if ((candidate.attachmentUrls ?? []).includes(marker)) {
+ skip(candidate.identifier, 'already-notified');
+ continue;
+ }
+
+ const changeset = await readChangesetProse(candidate, { fixReferences });
+ const text =
+ changeset === null
+ ? null
+ : composeReply({
+ changeset,
+ version: gate.version,
+ originChannel: origin.channel,
+ coverage: gate.coverage,
+ });
+
+ if (!text) {
+ log(
+ `::warning::write-back: ${candidate.identifier} shipped in v${gate.version} but has no changeset prose ` +
+ 'to quote; posting nothing rather than a bare version.',
+ );
+ skip(candidate.identifier, 'no-prose');
+ continue;
+ }
+
+ if (!live) {
+ log(
+ `::notice::write-back: [dry run] would reply to ${origin.url} for ${candidate.identifier} ` +
+ `(v${gate.version}, covers ${gate.coverage.join(', ')}).`,
+ );
+ posted.push({ identifier: candidate.identifier, origin: origin.url, version: gate.version, dryRun: true });
+ continue;
+ }
+
+ // Mark before posting, not after. The contract is at-most-once, and the
+ // two failure windows are not symmetric: a crash between post and mark
+ // re-sends a reply the reporter already read, while a crash between mark
+ // and post just leaves them uninformed, which is the same state they were
+ // in a moment earlier and which a human can still fix by hand.
+ await recordNotification({
+ issueId: candidate.id,
+ url: marker,
+ title: `Reporter notified: v${gate.version}`,
+ });
+ // The window between these two is the one state an operator cannot infer
+ // from the failure alone: marked, so no later run will retry, but never
+ // actually delivered. Name it here so it is readable from the job log
+ // rather than only from a Linear lookup.
+ log(
+ `::debug::write-back: marker written for ${origin.url} (${candidate.identifier}); posting reply next.`,
+ );
+ await postReply(origin, text);
+ log(`::notice::write-back: replied to ${origin.url} for ${candidate.identifier} (v${gate.version}).`);
+ posted.push({ identifier: candidate.identifier, origin: origin.url, version: gate.version, dryRun: false });
+ }
+ }
+
+ return { posted, skipped, dryRun: !live };
+}
+
+// --- workflow-runtime wiring (real Linear / git / gh / Discord boundary) ---
+
+async function linearGraphql({ apiKey, query, variables }) {
+ const res = await fetch(LINEAR_GRAPHQL_URL, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', authorization: apiKey },
+ body: JSON.stringify({ query, variables }),
+ });
+ if (!res.ok) {
+ throw new Error(`Linear GraphQL returned HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);
+ }
+ const payload = await res.json();
+ if (payload.errors?.length) {
+ throw new Error(`Linear GraphQL error: ${payload.errors.map((e) => e.message).join('; ')}`);
+ }
+ return payload.data;
+}
+
+function toNode(raw) {
+ return {
+ id: raw.id,
+ identifier: raw.identifier,
+ stateType: raw.state?.type ?? 'unknown',
+ labels: (raw.labels?.nodes ?? []).map((l) => l.name),
+ attachmentUrls: (raw.attachments?.nodes ?? []).map((a) => a.url),
+ };
+}
+
+async function paginate({ apiKey, query, variables }) {
+ const collected = [];
+ let after = null;
+ do {
+ const data = await linearGraphql({ apiKey, query, variables: { ...variables, after } });
+ const page = data?.issues;
+ if (!page) throw new Error('Linear returned no issues connection; refusing to treat that as an empty result.');
+ collected.push(...page.nodes.map(toNode));
+ after = page.pageInfo?.hasNextPage ? page.pageInfo.endCursor : null;
+ } while (after);
+ return collected;
+}
+
+function runGit(args) {
+ const res = spawnSync('git', args, { encoding: 'utf8' });
+ if (res.status !== 0) {
+ throw new Error(`git ${args.join(' ')} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`);
+ }
+ return String(res.stdout || '');
+}
+
+function realStableTags() {
+ return runGit(['tag', '--list', 'v*', '--sort=version:refname'])
+ .split('\n')
+ .map((t) => t.trim())
+ .filter((t) => STABLE_TAG_RE.test(t));
+}
+
+const REC_SEP = '\x1e';
+const UNIT_SEP = '\x1f';
+
+function realFindMirroredCommits(privateSha) {
+ const out = runGit([
+ 'log',
+ '--all',
+ '--fixed-strings',
+ `--grep=GitOrigin-RevId: ${privateSha}`,
+ `--format=%H${UNIT_SEP}%B${REC_SEP}`,
+ ]);
+ const commits = [];
+ for (const record of out.split(REC_SEP)) {
+ const trimmed = record.replace(/^\n+/, '');
+ if (!trimmed.trim()) continue;
+ const sep = trimmed.indexOf(UNIT_SEP);
+ if (sep === -1) continue;
+ commits.push({ sha: trimmed.slice(0, sep).trim(), message: trimmed.slice(sep + 1) });
+ }
+ return commits;
+}
+
+function realContains(tag, sha) {
+ const res = spawnSync('git', ['merge-base', '--is-ancestor', sha, `${tag}^{commit}`], { encoding: 'utf8' });
+ if (res.status === 0) return true;
+ if (res.status === 1) return false;
+ throw new Error(
+ `git merge-base --is-ancestor ${sha} ${tag} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`,
+ );
+}
+
+function gh(args) {
+ return execFileSync('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+function realResolvePrMergeSha({ owner, repo, number }) {
+ let out;
+ try {
+ out = gh(['api', `repos/${owner}/${repo}/pulls/${number}`, '--jq', '.merged_at,.merge_commit_sha']);
+ } catch (err) {
+ throw new Error(
+ `gh api repos/${owner}/${repo}/pulls/${number} failed: ${String(err?.stderr || err?.message || '').trim()}`,
+ );
+ }
+ const [mergedAt, sha] = out.split('\n').map((s) => s.trim());
+ if (!mergedAt || mergedAt === 'null') {
+ throw new Error(`${owner}/${repo}#${number} is not merged; there is no fix commit to resolve.`);
+ }
+ if (!FULL_SHA_RE.test(sha || '')) {
+ throw new Error(`${owner}/${repo}#${number} has no usable merge_commit_sha (got '${sha}').`);
+ }
+ return sha.toLowerCase();
+}
+
+/**
+ * The prose quoted back to the reporter is the changeset the fix shipped with,
+ * which is already public release-notes copy. It is read from the fix pull
+ * request's own `.changeset/*.md` addition rather than from the ticket, so no
+ * internal field is ever in reach.
+ */
+function realReadChangesetProse(_candidate, { fixReferences }) {
+ const pull = fixReferences.find((ref) => ref.channel === 'pull-request');
+ if (!pull) return null;
+
+ let names;
+ try {
+ names = gh([
+ 'api',
+ `repos/${pull.owner}/${pull.repo}/pulls/${pull.number}/files`,
+ '--paginate',
+ '--jq',
+ '.[].filename',
+ ]);
+ } catch (err) {
+ throw new Error(`gh api pulls/${pull.number}/files failed: ${String(err?.stderr || err?.message || '').trim()}`);
+ }
+
+ const changesetPath = names
+ .split('\n')
+ .map((s) => s.trim())
+ .find((name) => /^\.changeset\/[^/]+\.md$/.test(name) && !name.endsWith('/README.md'));
+ if (!changesetPath) return null;
+
+ let raw;
+ try {
+ raw = gh([
+ 'api',
+ // Read at the PR head rather than at the default branch: the changeset
+ // file is consumed and deleted when the release that shipped it was cut.
+ `repos/${pull.owner}/${pull.repo}/contents/${changesetPath}?ref=refs/pull/${pull.number}/head`,
+ '--jq',
+ '.content',
+ ]);
+ } catch (err) {
+ throw new Error(`gh api contents/${changesetPath} failed: ${String(err?.stderr || err?.message || '').trim()}`);
+ }
+
+ const decoded = Buffer.from(raw.replace(/\s+/g, ''), 'base64').toString('utf8');
+ return parseChangeset(decoded);
+}
+
+/** Strip the `---`-delimited bump block; what remains is the release note. */
+export function parseChangeset(raw) {
+ const text = String(raw ?? '');
+ const withoutFrontmatter = text.replace(/^\s*---[\s\S]*?---\s*/, '').trim();
+ if (!withoutFrontmatter) return null;
+ const [firstLine] = withoutFrontmatter.split('\n');
+ return { title: firstLine.trim(), body: withoutFrontmatter };
+}
+
+async function realPostReply(origin, text) {
+ if (origin.channel === 'github-issue') {
+ execFileSync(
+ 'gh',
+ ['api', `repos/${origin.owner}/${origin.repo}/issues/${origin.number}/comments`, '-f', `body=${text}`],
+ { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+ );
+ return;
+ }
+ if (origin.channel === 'discord-thread') {
+ // The bot token never leaves Railway, so this goes through the deployed
+ // bot's authenticated endpoint rather than carrying a Discord credential
+ // into Actions. The release-announcement webhook is NOT an alternative: a
+ // webhook is bound to one channel and could only reach threads inside it,
+ // so a reply sent that way would land where the reporter never looks.
+ const url = process.env.DISCORD_NOTIFY_URL;
+ const token = process.env.DISCORD_NOTIFY_TOKEN;
+ if (!url || !token) throw new Error('DISCORD_NOTIFY_URL / DISCORD_NOTIFY_TOKEN are required to reply on Discord');
+ const res = await fetch(url, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+ body: JSON.stringify({ threadId: origin.threadId, content: text }),
+ });
+ if (!res.ok) {
+ throw new Error(`notify endpoint returned HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+ }
+ return;
+ }
+ throw new Error(`no reply transport for origin channel '${origin.channel}'`);
+}
+
+async function main() {
+ const log = (message) => console.log(message);
+ const apiKey = (process.env.LINEAR_API_KEY ?? '').trim();
+ if (!apiKey) {
+ console.log(
+ '::notice::write-back: LINEAR_API_KEY is not set on this repo, so there is nothing to enumerate. ' +
+ 'Add it as a repo secret to enable reporter write-back. Nothing was posted.',
+ );
+ return;
+ }
+
+ const live = process.env.WRITE_BACK_MODE === 'live';
+ if (!live) {
+ log('::notice::write-back: running in dry-run mode (set WRITE_BACK_MODE=live to arm reporter replies).');
+ }
+
+ const stableTags = realStableTags();
+ const versionFor = (node) =>
+ deriveVersionForFixRefs({
+ fixReferences: partitionAttachments(node.attachmentUrls ?? []).fixReferences,
+ stableTags,
+ findMirroredCommits: realFindMirroredCommits,
+ contains: realContains,
+ resolvePrMergeSha: realResolvePrMergeSha,
+ log,
+ });
+
+ const result = await runWriteBack({
+ listCandidates: () => paginate({ apiKey, query: CANDIDATE_QUERY, variables: {} }),
+ listChildren: (parentId) => paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId } }),
+ versionFor,
+ readChangesetProse: (candidate, ctx) => realReadChangesetProse(candidate, ctx),
+ postReply: realPostReply,
+ recordNotification: async ({ issueId, url, title }) => {
+ const data = await linearGraphql({
+ apiKey,
+ query:
+ 'mutation Mark($input: AttachmentCreateInput!) { attachmentCreate(input: $input) { success } }',
+ variables: { input: { issueId, url, title } },
+ });
+ // A dropped marker is not cosmetic: it is what stops the next run
+ // replying to the same reporter again.
+ if (!data?.attachmentCreate?.success) {
+ throw new Error(`Linear attachmentCreate reported failure for issue ${issueId}`);
+ }
+ },
+ live,
+ log,
+ });
+
+ console.log(JSON.stringify({ dryRun: result.dryRun, posted: result.posted.length, skipped: result.skipped }));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ main().catch((err) => {
+ console.error(`::error::write-back: ${err.message}`);
+ process.exit(1);
+ });
+}
diff --git a/.github/scripts/write-back.test.mjs b/.github/scripts/write-back.test.mjs
new file mode 100644
index 000000000..725eec82f
--- /dev/null
+++ b/.github/scripts/write-back.test.mjs
@@ -0,0 +1,379 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, test } from 'vitest';
+import {
+ CANDIDATE_QUERY,
+ deriveVersionForFixRefs,
+ notificationMarkerUrl,
+ parseChangeset,
+ runWriteBack,
+} from './write-back.mjs';
+
+const GH_ISSUE = 'https://github.com/inkeep/open-knowledge/issues/769';
+const GH_PULL = 'https://github.com/inkeep/agents-private/pull/2844';
+const SLACK_ARCHIVE = 'https://inkeep.slack.com/archives/C016VCYCL74/p1727122965001469';
+const DISCORD_THREAD = 'https://discord.com/channels/1514363990740828223/1528881792063508610';
+const CHANGESET = { title: 'Honor backslash escapes', body: 'Honor backslash escapes in the markdown promoters.' };
+
+// The real chain off the mirror: a private merge commit, its mirrored copy, and
+// the stable tag that first contains it.
+const PRIVATE_SHA = 'da71f0c698ccaac11da915169ca6c7d585d5eb97';
+const MIRRORED_SHA = 'eb52a625cd86859a8ec43ddc8f96e9b418d092a7';
+const STABLE_TAGS = ['v0.35.0', 'v0.35.2', 'v0.35.6', 'v0.36.0'];
+
+const candidate = (overrides = {}) => ({
+ id: 'uuid-7539',
+ identifier: 'PRD-7539',
+ stateType: 'completed',
+ labels: ['Bug', 'ok:platform'],
+ attachmentUrls: [GH_PULL, GH_ISSUE],
+ ...overrides,
+});
+
+// Every boundary is a plain closure. `writes` is the ledger the dry-run test
+// asserts stays empty.
+function harness(overrides = {}) {
+ const logs = [];
+ const writes = [];
+ const deps = {
+ listCandidates: async () => [candidate()],
+ listChildren: async () => [],
+ versionFor: async () => 'v0.36.0',
+ readChangesetProse: async () => CHANGESET,
+ postReply: async (origin, text) => writes.push({ kind: 'post', origin: origin.url, text }),
+ recordNotification: async (marker) => writes.push({ kind: 'mark', url: marker.url }),
+ log: (m) => logs.push(m),
+ ...overrides,
+ };
+ return { deps, logs, writes, run: () => runWriteBack(deps) };
+}
+
+describe('candidate enumeration', () => {
+ test('candidates come from a Linear ticket query, never from a walk over release commits', () => {
+ expect(CANDIDATE_QUERY).toContain('issues(');
+ expect(CANDIDATE_QUERY).toContain('state: { type: { eq: "completed" } }');
+ expect(CANDIDATE_QUERY).not.toMatch(/commits?\s*\(/);
+ });
+
+ test('the label filter matches any label, so a Bug ticket carrying a platform label is still enumerated', () => {
+ expect(CANDIDATE_QUERY).toContain('labels: { name: { eq: "Bug" } }');
+ // `labels: { every: ... }` reads almost the same and would drop every
+ // multi-labelled ticket, which in practice is nearly all of them.
+ expect(CANDIDATE_QUERY).not.toContain('every');
+ });
+
+ test('the not-yet-notified condition is not expressed inside the query', () => {
+ expect(CANDIDATE_QUERY).not.toMatch(/notified/i);
+ expect(CANDIDATE_QUERY).toContain('attachments');
+ });
+
+ test('the module imports the shared shipped-version resolver rather than reimplementing containment', () => {
+ const source = readFileSync(new URL('./write-back.mjs', import.meta.url), 'utf8');
+ expect(source).toMatch(/from '\.\/resolve-shipped-version\.mjs'/);
+ expect(source).toContain('resolveShippedVersion');
+ // The one place tag containment may be spelled out is the injected git
+ // boundary it hands to that resolver.
+ expect(source.match(/merge-base/g)?.length ?? 0).toBeLessThanOrEqual(2);
+ });
+});
+
+describe('version derivation', () => {
+ const findMirrored = (sha) =>
+ sha === PRIVATE_SHA ? [{ sha: MIRRORED_SHA, message: `subject\n\nGitOrigin-RevId: ${PRIVATE_SHA}\n` }] : [];
+ const containsFrom = (map) => (tag, sha) => (map[sha] ?? []).includes(tag);
+
+ const derive = (overrides = {}) =>
+ deriveVersionForFixRefs({
+ stableTags: STABLE_TAGS,
+ findMirroredCommits: findMirrored,
+ contains: containsFrom({ [MIRRORED_SHA]: ['v0.36.0'] }),
+ resolvePrMergeSha: () => PRIVATE_SHA,
+ ...overrides,
+ });
+
+ test('a pull-request fix reference resolves through tag containment', () => {
+ expect(derive({ fixReferences: [{ channel: 'pull-request', url: GH_PULL }] })).toBe('0.36.0');
+ });
+
+ test('a commit fix reference resolves without needing a pull request', () => {
+ expect(
+ derive({
+ fixReferences: [{ channel: 'commit', url: 'https://github.com/x/y/commit/' + PRIVATE_SHA, sha: PRIVATE_SHA }],
+ resolvePrMergeSha: () => {
+ throw new Error('a commit reference must not need the pull-request hop');
+ },
+ }),
+ ).toBe('0.36.0');
+ });
+
+ test('across several fix references the answer is the highest, so the build contains all of them', () => {
+ const otherSha = 'b'.repeat(40);
+ const otherMirrored = 'c'.repeat(40);
+ expect(
+ deriveVersionForFixRefs({
+ fixReferences: [
+ { channel: 'commit', url: 'u1', sha: PRIVATE_SHA },
+ { channel: 'commit', url: 'u2', sha: otherSha },
+ ],
+ stableTags: STABLE_TAGS,
+ findMirroredCommits: (sha) =>
+ sha === PRIVATE_SHA
+ ? [{ sha: MIRRORED_SHA, message: `GitOrigin-RevId: ${PRIVATE_SHA}` }]
+ : [{ sha: otherMirrored, message: `GitOrigin-RevId: ${otherSha}` }],
+ contains: containsFrom({
+ [MIRRORED_SHA]: ['v0.35.2', 'v0.35.6', 'v0.36.0'],
+ [otherMirrored]: ['v0.36.0'],
+ }),
+ resolvePrMergeSha: () => PRIVATE_SHA,
+ }),
+ ).toBe('0.36.0');
+ });
+
+ test('a fix reference that has not reached a stable release yields no version at all', () => {
+ expect(
+ derive({
+ fixReferences: [{ channel: 'commit', url: 'u', sha: PRIVATE_SHA }],
+ contains: () => false,
+ }),
+ ).toBeNull();
+ });
+
+ test('a ticket with no fix references yields no version rather than throwing', () => {
+ expect(derive({ fixReferences: [] })).toBeNull();
+ });
+
+ test('an infra failure in the git boundary propagates rather than reading as not-shipped', () => {
+ expect(() =>
+ derive({
+ fixReferences: [{ channel: 'commit', url: 'u', sha: PRIVATE_SHA }],
+ contains: () => {
+ throw new Error('git exploded');
+ },
+ }),
+ ).toThrow(/git exploded/);
+ });
+});
+
+describe('idempotency marker', () => {
+ test('the marker url is deterministic in the origin and the version', () => {
+ const a = notificationMarkerUrl({ version: '0.36.0', originUrl: GH_ISSUE });
+ const b = notificationMarkerUrl({ version: 'v0.36.0', originUrl: GH_ISSUE });
+ expect(a).toBe(b);
+ expect(a).toContain('/releases/tag/v0.36.0');
+ expect(a).toContain(encodeURIComponent(GH_ISSUE));
+ });
+
+ test('a different origin or a different version yields a different marker', () => {
+ const base = notificationMarkerUrl({ version: '0.36.0', originUrl: GH_ISSUE });
+ expect(notificationMarkerUrl({ version: '0.36.1', originUrl: GH_ISSUE })).not.toBe(base);
+ expect(notificationMarkerUrl({ version: '0.36.0', originUrl: `${GH_ISSUE}0` })).not.toBe(base);
+ });
+});
+
+describe('write-back run', () => {
+ test('with no explicit live mode it composes and logs but performs no writes at all', async () => {
+ const h = harness();
+ const result = await h.run();
+ expect(result.dryRun).toBe(true);
+ expect(h.writes).toEqual([]);
+ expect(result.posted).toHaveLength(1);
+ expect(h.logs.some((m) => m.includes('[dry run]'))).toBe(true);
+ });
+
+ test('in live mode it records the notification before posting to the origin', async () => {
+ const h = harness({ live: true });
+ await h.run();
+ // The order is the at-most-once guarantee, not an incidental detail. Were
+ // the reply to land first, a crash before the marker was written would
+ // re-send a reply the reporter had already read on the next run.
+ expect(h.writes.map((w) => w.kind)).toEqual(['mark', 'post']);
+ const post = h.writes.find((w) => w.kind === 'post');
+ const mark = h.writes.find((w) => w.kind === 'mark');
+ expect(post.origin).toBe(GH_ISSUE);
+ expect(post.text).toContain('v0.36.0');
+ expect(mark.url).toBe(notificationMarkerUrl({ version: '0.36.0', originUrl: GH_ISSUE }));
+ });
+
+ test('a discord-thread origin is composed for Discord, not just classified as one', async () => {
+ const h = harness({
+ live: true,
+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, DISCORD_THREAD] })],
+ });
+ await h.run();
+ const post = h.writes.find((w) => w.kind === 'post');
+ // The gate's own tests pin the two formattings; what this pins is the
+ // wiring between them, which a rename anywhere along
+ // classify -> origin.channel -> composeReply would sever silently while
+ // every unit test still passed.
+ expect(post.origin).toBe(DISCORD_THREAD);
+ expect(post.text).toContain('<https://github.com/inkeep/open-knowledge/releases>');
+ });
+
+ test('a failure while recording the marker leaves the reporter unmessaged', async () => {
+ const h = harness({
+ live: true,
+ recordNotification: async () => {
+ throw new Error('Linear attachmentCreate reported failure');
+ },
+ });
+ await expect(h.run()).rejects.toThrow(/attachmentCreate/);
+ expect(h.writes.filter((w) => w.kind === 'post')).toHaveLength(0);
+ });
+
+ test('running twice against the same release posts exactly once', async () => {
+ const marker = notificationMarkerUrl({ version: '0.36.0', originUrl: GH_ISSUE });
+ const first = harness({ live: true });
+ await first.run();
+ expect(first.writes.filter((w) => w.kind === 'post')).toHaveLength(1);
+
+ // The second run sees the marker the first one recorded, exactly as a
+ // re-read of the ticket would.
+ const second = harness({
+ live: true,
+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, GH_ISSUE, marker] })],
+ });
+ const result = await second.run();
+ expect(second.writes).toEqual([]);
+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'already-notified' }]);
+ });
+
+ test('a candidate whose version cannot be derived posts nothing and warns distinguishably', async () => {
+ const h = harness({ live: true, versionFor: async () => null });
+ const result = await h.run();
+ expect(h.writes).toEqual([]);
+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'version-underivable' }]);
+ expect(h.logs.some((m) => m.startsWith('::warning::') && m.includes('no stable release could be derived'))).toBe(
+ true,
+ );
+ });
+
+ test('a candidate whose only origin cannot be replied to posts nothing and warns', async () => {
+ const h = harness({
+ live: true,
+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, SLACK_ARCHIVE] })],
+ });
+ const result = await h.run();
+ expect(h.writes).toEqual([]);
+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'origin-unrepliable' }]);
+ expect(h.logs.some((m) => m.startsWith('::warning::') && m.includes('nowhere to post'))).toBe(true);
+ });
+
+ test('a candidate with no origin at all is skipped quietly, because not every fix has a reporter', async () => {
+ const h = harness({ live: true, listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL] })] });
+ const result = await h.run();
+ expect(h.writes).toEqual([]);
+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'no-origin' }]);
+ expect(h.logs.some((m) => m.startsWith('::warning::'))).toBe(false);
+ });
+
+ test('an outstanding descendant withholds the whole reply', async () => {
+ const h = harness({
+ live: true,
+ listChildren: async () => [
+ { id: 'a', identifier: 'PRD-7398', stateType: 'completed', labels: ['Bug'], attachmentUrls: [] },
+ { id: 'b', identifier: 'PRD-7401', stateType: 'unstarted', labels: [], attachmentUrls: [] },
+ ],
+ });
+ const result = await h.run();
+ expect(h.writes).toEqual([]);
+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'fan-in-withheld' }]);
+ });
+
+ test('a candidate with no changeset prose posts nothing rather than a bare version', async () => {
+ const h = harness({ live: true, readChangesetProse: async () => null });
+ const result = await h.run();
+ expect(h.writes).toEqual([]);
+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'no-prose' }]);
+ expect(h.logs.some((m) => m.startsWith('::warning::') && m.includes('no changeset prose'))).toBe(true);
+ });
+
+ test('an infra failure throws out of the run rather than being folded into silence', async () => {
+ const h = harness({
+ live: true,
+ listCandidates: async () => {
+ throw new Error('Linear GraphQL returned HTTP 500');
+ },
+ });
+ await expect(h.run()).rejects.toThrow(/HTTP 500/);
+ });
+
+ test('the coverage of a fanned-in report reaches the reply', async () => {
+ const h = harness({
+ live: true,
+ listChildren: async () => [
+ { id: 'a', identifier: 'PRD-7398', stateType: 'completed', labels: ['Bug'], attachmentUrls: [] },
+ { id: 'b', identifier: 'PRD-7403', stateType: 'completed', labels: [], attachmentUrls: [] },
+ ],
+ });
+ await h.run();
+ expect(h.writes.find((w) => w.kind === 'post').text).toContain('Covers PRD-7398, PRD-7403.');
+ });
+});
+
+describe('changeset parsing', () => {
+ test('the bump block is stripped and the release note is what remains', () => {
+ const parsed = parseChangeset(
+ ['---', "'@inkeep/open-knowledge': patch", '---', '', 'Honor backslash escapes in the promoters.', ''].join(
+ '\n',
+ ),
+ );
+ expect(parsed).toEqual({
+ title: 'Honor backslash escapes in the promoters.',
+ body: 'Honor backslash escapes in the promoters.',
+ });
+ });
+
+ test('a multi-line note keeps its first line as the title and its whole text as the body', () => {
+ const parsed = parseChangeset(['---', "'x': patch", '---', '', 'Short subject', '', 'More detail.'].join('\n'));
+ expect(parsed.title).toBe('Short subject');
+ expect(parsed.body).toContain('More detail.');
+ });
+
+ test('a changeset with no prose yields nothing rather than an empty reply', () => {
+ expect(parseChangeset(['---', "'x': patch", '---', ''].join('\n'))).toBeNull();
+ expect(parseChangeset('')).toBeNull();
+ });
+});
+
+// The properties that keep a reporter-facing side effect from ever touching a
+// release: its own trigger, its own concurrency group, and no edit to any of
+// the three publish workflows.
+describe('workflow shape', () => {
+ const read = (name) => readFileSync(new URL(`../workflows/${name}`, import.meta.url), 'utf8');
+ const workflow = read('write-back.yml');
+
+ test('it triggers on the existing release dispatch rather than on release published', () => {
+ expect(workflow).toMatch(/repository_dispatch:\s*\n\s*types:\s*\[desktop-release\]/);
+ expect(workflow).not.toMatch(/^\s{2}release:/m);
+ expect(workflow).not.toContain('types: [published]');
+ });
+
+ test('only a bare stable tag runs the write-back', () => {
+ expect(workflow).toContain('^v[0-9]+\\.[0-9]+\\.[0-9]+$');
+ expect(workflow).toMatch(/if:\s*steps\.tag\.outputs\.stable == 'true'/);
+ });
+
+ test('it carries its own concurrency group so a release can never queue behind it', () => {
+ const group = /concurrency:\s*\n(?:\s*#.*\n)*\s*group:\s*(.+)/.exec(workflow)?.[1] ?? '';
+ expect(group).toContain('reporter-write-back');
+ for (const other of ['release.yml', 'promote-stable.yml', 'linear-release.yml']) {
+ const otherGroup = /concurrency:\s*\n(?:\s*#.*\n)*\s*group:\s*(.+)/.exec(read(other))?.[1] ?? '';
+ expect(group.trim()).not.toBe(otherGroup.trim());
+ }
+ });
+
+ test('the checkout provides full history and tags so containment can be computed', () => {
+ expect(workflow).toContain('fetch-depth: 0');
+ expect(workflow).toContain('fetch-tags: true');
+ });
+
+ test('no release workflow references the write-back, so it cannot fail a release', () => {
+ for (const name of ['release.yml', 'promote-stable.yml', 'desktop-release.yml']) {
+ expect(read(name)).not.toMatch(/write-back/i);
+ }
+ });
+
+ test('live posting needs an explicit mode on top of the credential', () => {
+ expect(workflow).toContain('WRITE_BACK_MODE');
+ expect(workflow).toContain('LINEAR_API_KEY');
+ });
+});
diff --git a/.github/workflows/write-back.yml b/.github/workflows/write-back.yml
new file mode 100644
index 000000000..8d28b54bd
--- /dev/null
+++ b/.github/workflows/write-back.yml
@@ -0,0 +1,101 @@
+name: Reporter Write-Back
+
+# Tell bug reporters, once, that the fix they reported has shipped.
+#
+# HOW IT'S TRIGGERED (no edits to the delicate publish path)
+# release.yml (beta) and promote-stable.yml (stable) both already fire a
+# repository_dispatch event_type=desktop-release carrying
+# client_payload.{release_tag, ref}. This piggybacks on that same event, the
+# way linear-release.yml already does, so the publish workflows stay
+# byte-untouched. `release: published` is not an option: GitHub suppresses
+# cascades from GITHUB_TOKEN-authored release events, and repository_dispatch
+# is the documented exemption.
+#
+# Only a bare vX.Y.Z runs. A `-beta.N` cut is a no-op: a reporter told their
+# fix is out should be able to install it from the default channel, and a beta
+# is not that.
+#
+# WHY IT IS DECOUPLED
+# This posts in public under the project's name and it runs after a release
+# has already happened. Nothing it does may reach back into the release: it
+# has its own trigger and its own concurrency group, so it can never queue
+# behind or delay a cut, and no release workflow waits on its result. The
+# worst outcome available to a failure here is that nobody gets told.
+#
+# EVERYTHING SHIPS INERT
+# With no LINEAR_API_KEY the script emits a notice and enumerates nothing.
+# With the key but no WRITE_BACK_MODE it composes replies and logs them
+# without performing a single write. Live posting therefore needs two
+# deliberate operator actions, so wiring up credentials cannot arm
+# reporter-facing posts by accident. Both steps are in RELEASES.md.
+
+on:
+ repository_dispatch:
+ types: [desktop-release]
+ # Manual backfill / dry-run rehearsal against a specific tag.
+ workflow_dispatch:
+ inputs:
+ release_tag:
+ description: "Stable release tag to notify reporters about (e.g. v0.36.0)"
+ required: true
+ type: string
+
+permissions:
+ contents: read
+ # Posting the reply onto a GitHub issue origin in this repo.
+ issues: write
+
+concurrency:
+ # Its own group, deliberately not the release cadence group: a write-back run
+ # must never be something a release cut can end up waiting on.
+ group: reporter-write-back-${{ github.event.client_payload.release_tag || inputs.release_tag }}
+ cancel-in-progress: false
+
+jobs:
+ notify:
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ env:
+ RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}
+ steps:
+ - name: Decide whether this tag is a stable release
+ id: tag
+ run: |
+ set -euo pipefail
+ if [[ -z "${RELEASE_TAG}" ]]; then
+ echo "::error::No release tag (neither client_payload.release_tag nor inputs.release_tag)."
+ exit 1
+ fi
+ if [[ "${RELEASE_TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ echo "stable=true" >> "$GITHUB_OUTPUT"
+ else
+ echo "stable=false" >> "$GITHUB_OUTPUT"
+ echo "::notice::${RELEASE_TAG} is not a bare stable tag; reporters are only told about stable releases."
+ fi
+
+ - name: Checkout with full history and tags
+ if: steps.tag.outputs.stable == 'true'
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ # Tag containment is how the shipped version is derived, so every
+ # stable tag and the full history behind them have to be present.
+ fetch-depth: 0
+ fetch-tags: true
+ persist-credentials: false
+
+ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+ if: steps.tag.outputs.stable == 'true'
+ with:
+ node-version: "24"
+
+ - name: Notify reporters whose fix reached this release
+ if: steps.tag.outputs.stable == 'true'
+ env:
+ GH_TOKEN: ${{ github.token }}
+ LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
+ # Absent by default. Set to `live` on the repo (a variable, not a
+ # secret, so it is visible in the settings UI) to arm real posts.
+ WRITE_BACK_MODE: ${{ vars.WRITE_BACK_MODE }}
+ DISCORD_NOTIFY_URL: ${{ secrets.DISCORD_NOTIFY_URL }}
+ DISCORD_NOTIFY_TOKEN: ${{ secrets.DISCORD_NOTIFY_TOKEN }}
+ run: node .github/scripts/write-back.mjs