scripts/rollback-guard.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1// SHOULD THE LIVE GATE'S ROLLBACK ACTUALLY ROLL ANYTHING BACK?
2//
3// The rollback step exists to undo THE DEPLOY THIS RUN SHIPPED when the live gate
4// refuses it. A workflow `if:` on `needs.deploy.result` cannot express that: a rerun of
5// only the live job keeps attempt 1's 'success', so a second rollback would move
6// production onto whatever "the previous version" now is, which can be the refused
7// commit. A rollback of a deploy that is no longer live is wrong in either direction,
8// so the decision is made here, against what /health reports.
9//
10// Usage from the workflow:
11//
12//   node scripts/rollback-guard.mjs "<live sha from /health>" "<this run's GITHUB_SHA>" \
13//     "<run_attempt the deploy job ran in>" "<this run_attempt>"
14//
15// Exit 0 means roll back. Exit 1 means do not, and the reason is printed. Exit 2 means
16// the guard could not run, which is NOT permission to roll back.
17//
18//   node scripts/rollback-guard.mjs --after "<live sha after the rollback>" "<GITHUB_SHA>"
19//
20// Exit 0 means the rollback took effect: a readable sha other than this run's is live.
21// Exit 1 means it did not, or that what is live cannot be read.
22
23import { pathToFileURL } from "node:url";
24
25// A sha is at least 7 hex characters. A shorter value from /health would prefix-match
26// almost anything, so it counts as unreadable.
27const SHA = /^[0-9a-f]{7,40}$/;
28
29/**
30 * @param {string} liveSha the sha /health reports right now
31 * @param {string} runSha this run's own commit
32 * @param {{ deployAttempt?: string, runAttempt?: string }} [attempts] the run_attempt the
33 *   deploy job ran in, and this job's run_attempt
34 * @returns {{ roll: boolean, reason: string }}
35 */
36export function shouldRollBack(liveSha, runSha, attempts = {}) {
37  const live = String(liveSha ?? "").trim().toLowerCase();
38  const mine = String(runSha ?? "").trim().toLowerCase();
39
40  if (!SHA.test(mine)) {
41    return { roll: false, reason: "this run's own commit was not supplied as a sha, so there is nothing to compare the live sha against." };
42  }
43  // UNREADABLE: /health did not answer, did not parse, or carried no sha. When the
44  // deploy job ran in this same attempt, this attempt shipped the version now serving,
45  // and a deploy that broke /health most needs rolling back. In a rerun, or when the
46  // attempts are not supplied, it refuses and leaves it to a human.
47  if (!SHA.test(live)) {
48    const deploy = String(attempts.deployAttempt ?? "").trim();
49    const current = String(attempts.runAttempt ?? "").trim();
50    if (deploy && deploy === current) {
51      return {
52        roll: true,
53        reason: `/health reported '${liveSha}', not a sha, and the deploy job ran in this attempt (${current}), so what is serving is this attempt's deploy. Rolling it back.`,
54      };
55    }
56    return {
57      roll: false,
58      reason: `/health reported '${liveSha}', so what is live cannot be established, and the deploy job ran in attempt '${deploy}', not this attempt '${current}'. Refusing to roll back rather than moving production blind. A human decides this one.`,
59    };
60  }
61  // Either may be abbreviated: /health serves the full sha today, but the comparison
62  // should not depend on that.
63  const same = live.startsWith(mine) || mine.startsWith(live);
64  if (!same) {
65    return {
66      roll: false,
67      reason: `what is live is ${live}, not this run's commit ${mine}. The deploy this run shipped is already gone, so rolling back would move production off somebody else's deploy. This is the rerun case: it is what put the refused commit back into production on 2026-09-18.`,
68    };
69  }
70  return { roll: true, reason: `${live} is live and is this run's own commit, so the deploy this run shipped is the one being rolled back.` };
71}
72
73/**
74 * Did the rollback take effect? Only a readable sha other than this run's says so.
75 * @param {string} afterSha the sha /health reports after the rollback
76 * @param {string} runSha this run's own commit
77 * @returns {{ moved: boolean, reason: string }}
78 */
79export function rollbackTookEffect(afterSha, runSha) {
80  const after = String(afterSha ?? "").trim().toLowerCase();
81  const mine = String(runSha ?? "").trim().toLowerCase();
82  if (!SHA.test(after)) {
83    return { moved: false, reason: `/health reports '${afterSha}' after the rollback, so it cannot be shown that the rollback took effect.` };
84  }
85  if (!SHA.test(mine)) {
86    return { moved: false, reason: "this run's own commit was not supplied as a sha, so there is nothing to compare against." };
87  }
88  if (after.startsWith(mine) || mine.startsWith(after)) {
89    return { moved: false, reason: `${after} is still live after the rollback: the rollback did not take effect.` };
90  }
91  return { moved: true, reason: `${after} is live after the rollback.` };
92}
93
94// Skipped when imported by the test.
95if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
96  const args = process.argv.slice(2);
97  try {
98    if (args[0] === "--after") {
99      const after = rollbackTookEffect(args[1] ?? "", args[2] ?? "");
100      console.log(after.reason);
101      process.exit(after.moved ? 0 : 1);
102    }
103    const [liveSha, runSha, deployAttempt, runAttempt] = args;
104    const verdict = shouldRollBack(liveSha ?? "", runSha ?? "", { deployAttempt, runAttempt });
105    console.log(verdict.reason);
106    process.exit(verdict.roll ? 0 : 1);
107  } catch (err) {
108    console.error(`rollback-guard could not run: ${err instanceof Error ? err.message : String(err)}`);
109    process.exit(2);
110  }
111}