mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-11-16 17:09:09 +00:00
786 lines
34 KiB
JavaScript
786 lines
34 KiB
JavaScript
#!/usr/bin/env node
|
|
// scripts/merge-queue/apply-ruleset.mjs — WP6. Plan §3.9: apply the omni-queue rulesets.
|
|
//
|
|
// node scripts/merge-queue/apply-ruleset.mjs --base <branch> [--dry-run]
|
|
// [--repo <owner/repo>] [--app-id <id>] (--kind release, default)
|
|
// node scripts/merge-queue/apply-ruleset.mjs --kind queue-refs [--dry-run]
|
|
// [--repo <owner/repo>] [--app-id <id>]
|
|
//
|
|
// Two kinds, each a JSON template under config/merge-queue/:
|
|
// release ruleset.release.json — the status door of ONE release branch, found by name
|
|
// ("<template name>: <branch>"). No pull_request rule and no bypass actor: a commit
|
|
// reaches the branch (push or merge) only if it carries the land status
|
|
// (config.landing.statusContext) written by the queue's GitHub App, pinned with
|
|
// integration_id. The queue writes that status on the validated candidate right
|
|
// before landing it; the landing push is then made as config.landing.actor.
|
|
// queue-refs ruleset.queue-refs.json — the queue's own refs (omni-queue-state, omni-queue/**/*):
|
|
// only the App (its single bypass actor) may create, update or delete them. Takes no
|
|
// --base; the ruleset keeps the fixed name of its template.
|
|
// Created when absent, updated when its normalized form differs, left alone otherwise. --dry-run
|
|
// prints the diff and the REST body and performs no write.
|
|
//
|
|
// Landing path (release kind): afterwards it reads every rule GitHub enforces on the branch
|
|
// (GET /repos/{repo}/rules/branches/{base}) and reports rules from OTHER rulesets (for example
|
|
// "Require PR on default branch" on ~DEFAULT_BRANCH) that would reject the landing push because
|
|
// the landing actor is not one of their bypass actors (the App, or for `landing.actor: owner` the
|
|
// repository admin role / organization admins): a warning on --dry-run, exit 1 on a real apply.
|
|
//
|
|
// Production lock: a real apply (no --dry-run, either kind) against cheaper-inference/OmniRoute
|
|
// (or its old name diegosouzapw/OmniRoute, which redirects) is refused unless
|
|
// OMNI_QUEUE_ALLOW_PRODUCTION_RULESET=1. Checked twice: on the --repo string before any API
|
|
// call, then on the full_name GitHub resolves (redirects included) before any write. The
|
|
// cut-over is the owner's decision (docs/ops/OMNI_QUEUE.md → "Cut-over").
|
|
//
|
|
// Token: GITHUB_TOKEN, else `gh auth token` (execFile, never a shell). Never printed.
|
|
|
|
import { execFileSync } from "node:child_process";
|
|
import { readFileSync, realpathSync } from "node:fs";
|
|
import { dirname, join } from "node:path";
|
|
import { fileURLToPath } from "node:url";
|
|
import { parseArgs } from "node:util";
|
|
import { LANDING_ACTORS, loadConfig } from "./config.mjs";
|
|
import { sanitizeBase } from "./contracts.mjs";
|
|
import { createGitHubClient } from "./github.mjs";
|
|
|
|
const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
|
|
export const DEFAULT_TEMPLATE_PATH = join(ROOT, "config", "merge-queue", "ruleset.release.json");
|
|
export const QUEUE_REFS_TEMPLATE_PATH = join(
|
|
ROOT,
|
|
"config",
|
|
"merge-queue",
|
|
"ruleset.queue-refs.json"
|
|
);
|
|
|
|
/** The rulesets this script applies (`--kind`). */
|
|
export const RULESET_KINDS = Object.freeze(["release", "queue-refs"]);
|
|
|
|
/** Placeholder replaced by the base branch in conditions.ref_name.include. */
|
|
export const BASE_PLACEHOLDER = "{{base}}";
|
|
|
|
/** Placeholder replaced by config.landing.statusContext in the required status check. */
|
|
export const STATUS_CONTEXT_PLACEHOLDER = "{{statusContext}}";
|
|
|
|
/** Repositories (lowercase owner/repo) where a real apply needs the explicit override. */
|
|
export const PRODUCTION_REPOSITORIES = Object.freeze([
|
|
"cheaper-inference/omniroute",
|
|
"diegosouzapw/omniroute",
|
|
]);
|
|
|
|
/**
|
|
* Rule types that would make the PR's own checks a merge requirement (never wanted here). The one
|
|
* exception is a single required_status_checks rule carrying only the land status context
|
|
* (buildRuleset enforces it): the queue itself writes that status on the candidate.
|
|
*/
|
|
export const CHECK_REQUIRING_RULE_TYPES = Object.freeze([
|
|
"required_status_checks",
|
|
"required_deployments",
|
|
"merge_queue",
|
|
"workflows",
|
|
"code_scanning",
|
|
]);
|
|
|
|
/** The only parameters the required_status_checks rule of a template may carry. */
|
|
const STATUS_RULE_PARAMETER_KEYS = Object.freeze([
|
|
"strict_required_status_checks_policy",
|
|
"do_not_enforce_on_create",
|
|
"required_status_checks",
|
|
]);
|
|
|
|
const BRANCH_RE = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
|
|
const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
|
|
const APP_ID_RE = /^[1-9][0-9]{0,15}$/;
|
|
const STATUS_CONTEXT_RE = /^[A-Za-z0-9._/-]{1,100}$/; // same rule as config.landing.statusContext
|
|
|
|
/** Repository role id of "Admin" (the repository owner's token acts as this role). */
|
|
const REPOSITORY_ADMIN_ROLE_ID = 5;
|
|
|
|
const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
|
|
|
|
function stripPrivateKeys(value) {
|
|
if (Array.isArray(value)) return value.map(stripPrivateKeys);
|
|
if (!isRecord(value)) return value;
|
|
const out = {};
|
|
for (const [key, v] of Object.entries(value)) {
|
|
if (!key.startsWith("_")) out[key] = stripPrivateKeys(v);
|
|
}
|
|
return out;
|
|
}
|
|
|
|
/** Throws unless `base` is a plain branch name (no wildcard, no refs/ prefix, no `..`). */
|
|
export function assertBranchName(base) {
|
|
const name = String(base ?? "");
|
|
if (
|
|
!BRANCH_RE.test(name) ||
|
|
name.startsWith("refs/") ||
|
|
name.includes("..") ||
|
|
name.split("/").some((seg) => seg.startsWith(".") || seg.endsWith(".lock"))
|
|
)
|
|
throw new Error(`invalid base branch: ${JSON.stringify(base)}`);
|
|
sanitizeBase(name); // same rule the queue uses for its own ref names
|
|
return name;
|
|
}
|
|
|
|
/**
|
|
* Fill a template. The release template needs a base: conditions.ref_name.include =
|
|
* ["refs/heads/<base>"] and the name suffixed with it. A template without the base placeholder
|
|
* (queue-refs) takes no base and keeps its fixed name and refs.
|
|
* The required status check (release): context = statusContext, integration_id = appId.
|
|
* The Integration bypass actor slot (queue-refs): actor_id = appId.
|
|
* appId null → the integration_id / Integration bypass actor is left out (dry-run preview only:
|
|
* main() refuses a real apply without it, because that pin / bypass is what scopes the rule to
|
|
* the queue's App).
|
|
* @param {object} template parsed ruleset.release.json or ruleset.queue-refs.json
|
|
* @param {{base?: string, appId?: number|null, statusContext?: string}} input
|
|
* @returns {object} REST body for POST/PUT /repos/{owner}/{repo}/rulesets
|
|
*/
|
|
export function buildRuleset(template, input) {
|
|
const hasBase = input?.base !== undefined && input?.base !== null;
|
|
const base = hasBase ? assertBranchName(input.base) : null;
|
|
const appId = input?.appId ?? null;
|
|
if (appId !== null && (!Number.isSafeInteger(appId) || appId <= 0))
|
|
throw new Error(`invalid app id: ${JSON.stringify(appId)}`);
|
|
if (!isRecord(template)) throw new Error("ruleset template: expected an object");
|
|
if (typeof template.name !== "string" || !template.name.trim())
|
|
throw new Error("ruleset template: name is required");
|
|
if (!Array.isArray(template.rules) || template.rules.length === 0)
|
|
throw new Error("ruleset template: rules are required");
|
|
const duplicated = duplicateRuleTypes(template.rules);
|
|
if (duplicated.length)
|
|
throw new Error(`ruleset template: duplicate rule types: ${duplicated.join(", ")}`);
|
|
const include = template.conditions?.ref_name?.include;
|
|
if (!Array.isArray(include) || include.length === 0)
|
|
throw new Error("ruleset template: conditions.ref_name.include is required");
|
|
const usesBase = include.some((r) => String(r).includes(BASE_PLACEHOLDER));
|
|
if (hasBase && !usesBase)
|
|
throw new Error(`ruleset template: conditions.ref_name.include needs ${BASE_PLACEHOLDER}`);
|
|
if (!hasBase && usesBase) assertBranchName(input?.base); // throws: a base is required
|
|
|
|
const body = stripPrivateKeys(structuredClone(template));
|
|
body.name = hasBase ? `${template.name.trim()}: ${base}` : template.name.trim();
|
|
body.conditions.ref_name.include = include.map((r) =>
|
|
String(r).replaceAll(BASE_PLACEHOLDER, base ?? "")
|
|
);
|
|
if (!Array.isArray(body.conditions.ref_name.exclude)) body.conditions.ref_name.exclude = [];
|
|
body.rules = body.rules.map((rule) =>
|
|
fillRule(rule, { appId, statusContext: input?.statusContext })
|
|
);
|
|
body.bypass_actors = (Array.isArray(body.bypass_actors) ? body.bypass_actors : []).flatMap(
|
|
(actor) => {
|
|
if (actor?.actor_type !== "Integration" || actor.actor_id !== null) return [actor];
|
|
return appId === null ? [] : [{ ...actor, actor_id: appId }];
|
|
}
|
|
);
|
|
if (JSON.stringify(body).includes("{{"))
|
|
throw new Error("ruleset template: unresolved placeholder");
|
|
return body;
|
|
}
|
|
|
|
/**
|
|
* Resolve the placeholders of one rule and refuse the check-requiring rules that are not the land
|
|
* status: required_status_checks stays forbidden except as exactly one rule carrying exactly one
|
|
* check (the land status context, pinned to the App), never strict.
|
|
*/
|
|
function fillRule(rule, { appId, statusContext }) {
|
|
const type = String(rule?.type);
|
|
if (!CHECK_REQUIRING_RULE_TYPES.includes(type)) return rule;
|
|
if (type !== "required_status_checks")
|
|
throw new Error(
|
|
`ruleset template: rule ${type} is not allowed (the only check-requiring rule is ` +
|
|
"required_status_checks, for the land status alone)"
|
|
);
|
|
if (typeof statusContext !== "string" || !STATUS_CONTEXT_RE.test(statusContext))
|
|
throw new Error(`invalid status context: ${JSON.stringify(statusContext)}`);
|
|
const parameters = rule.parameters;
|
|
if (!isRecord(parameters))
|
|
throw new Error("ruleset template: required_status_checks needs parameters");
|
|
for (const key of Object.keys(parameters)) {
|
|
if (!STATUS_RULE_PARAMETER_KEYS.includes(key))
|
|
throw new Error(`ruleset template: required_status_checks has an unexpected key: ${key}`);
|
|
}
|
|
if (parameters.strict_required_status_checks_policy !== false)
|
|
throw new Error(
|
|
"ruleset template: strict_required_status_checks_policy must be false (the queue " +
|
|
"validates the candidate against the base it lands on)"
|
|
);
|
|
if (parameters.do_not_enforce_on_create !== false)
|
|
throw new Error(
|
|
"ruleset template: do_not_enforce_on_create must be false (a branch created on a commit " +
|
|
"without the land status would get in)"
|
|
);
|
|
const checks = parameters.required_status_checks;
|
|
if (!Array.isArray(checks) || checks.length !== 1)
|
|
throw new Error(
|
|
`ruleset template: required_status_checks needs exactly one check (the land status ` +
|
|
`${JSON.stringify(statusContext)})`
|
|
);
|
|
const [check] = checks;
|
|
if (!isRecord(check)) throw new Error("ruleset template: the required status check is invalid");
|
|
for (const key of Object.keys(check)) {
|
|
if (key !== "context" && key !== "integration_id")
|
|
throw new Error(`ruleset template: the required status check has an unexpected key: ${key}`);
|
|
}
|
|
if (check.context !== STATUS_CONTEXT_PLACEHOLDER && check.context !== statusContext)
|
|
throw new Error(
|
|
`ruleset template: the only required status check allowed is the land status ` +
|
|
`${JSON.stringify(statusContext)} (got ${JSON.stringify(check.context)})`
|
|
);
|
|
if (check.integration_id !== null && check.integration_id !== undefined)
|
|
throw new Error(
|
|
"ruleset template: integration_id of the required status check is filled from --app-id"
|
|
);
|
|
const filled = { context: statusContext };
|
|
if (appId !== null) filled.integration_id = appId;
|
|
return { ...rule, parameters: { ...parameters, required_status_checks: [filled] } };
|
|
}
|
|
|
|
// ───────────────────────────── normalization / diff ─────────────────────────────
|
|
|
|
const sortStrings = (list) => [...(Array.isArray(list) ? list : [])].map(String).sort();
|
|
|
|
/** Rule types that appear more than once (GitHub allows one rule of each type per ruleset). */
|
|
function duplicateRuleTypes(rules) {
|
|
const seen = new Map();
|
|
for (const rule of Array.isArray(rules) ? rules : []) {
|
|
const type = String(rule?.type);
|
|
seen.set(type, (seen.get(type) ?? 0) + 1);
|
|
}
|
|
return [...seen].filter(([, n]) => n > 1).map(([type]) => type);
|
|
}
|
|
|
|
/** Parameters with "off" values (false/0/null/""/[]) dropped and keys sorted recursively. */
|
|
function canonicalParams(value) {
|
|
if (Array.isArray(value)) {
|
|
const items = value.map(canonicalParams);
|
|
return items.every((v) => typeof v !== "object" || v === null)
|
|
? [...items].sort((a, b) => String(a).localeCompare(String(b)))
|
|
: items;
|
|
}
|
|
if (!isRecord(value)) return value;
|
|
const out = {};
|
|
for (const key of Object.keys(value).sort()) {
|
|
const v = canonicalParams(value[key]);
|
|
if (v === false || v === 0 || v === null || v === undefined || v === "") continue;
|
|
if (Array.isArray(v) && v.length === 0) continue;
|
|
// GitHub echoes disabled sub-objects (dismissal_restriction: {enabled: false,
|
|
// allowed_actors: []}); once canonicalized they are empty and mean "unset".
|
|
if (isRecord(v) && Object.keys(v).length === 0) continue;
|
|
out[key] = v;
|
|
}
|
|
return out;
|
|
}
|
|
|
|
/**
|
|
* Canonical form used for the create/update/noop decision: server-only fields (id, node_id,
|
|
* _links, timestamps, source, current_user_can_bypass) are ignored, lists are sorted, and
|
|
* parameters that are off by default compare equal to their absence.
|
|
*/
|
|
export function normalizeRuleset(ruleset) {
|
|
const r = isRecord(ruleset) ? ruleset : {};
|
|
const rules = (Array.isArray(r.rules) ? r.rules : [])
|
|
.map((rule) => {
|
|
const parameters = canonicalParams(rule?.parameters ?? {});
|
|
return Object.keys(parameters).length
|
|
? { type: String(rule?.type), parameters }
|
|
: { type: String(rule?.type) };
|
|
})
|
|
.sort((a, b) => a.type.localeCompare(b.type));
|
|
const bypassActors = (Array.isArray(r.bypass_actors) ? r.bypass_actors : [])
|
|
.map((a) => ({
|
|
actor_type: String(a?.actor_type),
|
|
actor_id: a?.actor_id ?? null,
|
|
bypass_mode: String(a?.bypass_mode ?? "always"),
|
|
}))
|
|
.sort((a, b) => actorKey(a).localeCompare(actorKey(b)));
|
|
return {
|
|
name: r.name ?? null,
|
|
target: r.target ?? "branch",
|
|
enforcement: r.enforcement ?? null,
|
|
conditions: {
|
|
ref_name: {
|
|
include: sortStrings(r.conditions?.ref_name?.include),
|
|
exclude: sortStrings(r.conditions?.ref_name?.exclude),
|
|
},
|
|
},
|
|
rules,
|
|
bypass_actors: bypassActors,
|
|
};
|
|
}
|
|
|
|
function actorKey(actor) {
|
|
return `${actor.actor_type}:${actor.actor_id}`;
|
|
}
|
|
|
|
const show = (v) => (v === undefined ? "(unset)" : JSON.stringify(v));
|
|
|
|
/**
|
|
* Human-readable differences between the current ruleset (null = absent) and the desired one.
|
|
* Empty array = equivalent. Lines start with "+" (added), "-" (removed) or "~" (changed).
|
|
* @returns {string[]}
|
|
*/
|
|
export function diffRulesets(current, desired) {
|
|
const wantDuplicates = duplicateRuleTypes(desired?.rules);
|
|
if (wantDuplicates.length)
|
|
throw new Error(`desired ruleset has duplicate rule types: ${wantDuplicates.join(", ")}`);
|
|
const want = normalizeRuleset(desired);
|
|
if (current === null || current === undefined) {
|
|
return [
|
|
`+ name: ${show(want.name)}`,
|
|
`+ target: ${show(want.target)}`,
|
|
`+ enforcement: ${show(want.enforcement)}`,
|
|
`+ conditions.ref_name.include: ${show(want.conditions.ref_name.include)}`,
|
|
...(want.conditions.ref_name.exclude.length
|
|
? [`+ conditions.ref_name.exclude: ${show(want.conditions.ref_name.exclude)}`]
|
|
: []),
|
|
...want.rules.map((rule) => `+ rule ${rule.type}${ruleParams(rule)}`),
|
|
...want.bypass_actors.map((a) => `+ bypass ${actorKey(a)} (${a.bypass_mode})`),
|
|
];
|
|
}
|
|
const have = normalizeRuleset(current);
|
|
const lines = [];
|
|
for (const key of ["name", "target", "enforcement"]) {
|
|
if (have[key] !== want[key]) lines.push(`~ ${key}: ${show(have[key])} → ${show(want[key])}`);
|
|
}
|
|
for (const key of ["include", "exclude"]) {
|
|
const a = have.conditions.ref_name[key];
|
|
const b = want.conditions.ref_name[key];
|
|
if (JSON.stringify(a) !== JSON.stringify(b))
|
|
lines.push(`~ conditions.ref_name.${key}: ${show(a)} → ${show(b)}`);
|
|
}
|
|
// A Map keeps one rule per type: report the extra copies instead of hiding them.
|
|
for (const type of duplicateRuleTypes(have.rules)) {
|
|
const copies = have.rules.filter((rule) => rule.type === type).length;
|
|
lines.push(`- rule ${type}: ${copies - 1} duplicate(s) in the current ruleset`);
|
|
}
|
|
const haveRules = new Map(have.rules.map((rule) => [rule.type, rule]));
|
|
const wantRules = new Map(want.rules.map((rule) => [rule.type, rule]));
|
|
for (const [type, rule] of wantRules) {
|
|
const old = haveRules.get(type);
|
|
if (!old) {
|
|
lines.push(`+ rule ${type}${ruleParams(rule)}`);
|
|
continue;
|
|
}
|
|
const a = old.parameters ?? {};
|
|
const b = rule.parameters ?? {};
|
|
for (const param of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()) {
|
|
if (JSON.stringify(a[param]) !== JSON.stringify(b[param]))
|
|
lines.push(`~ rule ${type}.${param}: ${show(a[param])} → ${show(b[param])}`);
|
|
}
|
|
}
|
|
for (const [type, rule] of haveRules) {
|
|
if (!wantRules.has(type)) lines.push(`- rule ${type}${ruleParams(rule)}`);
|
|
}
|
|
const haveActors = new Map(have.bypass_actors.map((a) => [actorKey(a), a]));
|
|
const wantActors = new Map(want.bypass_actors.map((a) => [actorKey(a), a]));
|
|
for (const [key, actor] of wantActors) {
|
|
const old = haveActors.get(key);
|
|
if (!old) lines.push(`+ bypass ${key} (${actor.bypass_mode})`);
|
|
else if (old.bypass_mode !== actor.bypass_mode)
|
|
lines.push(`~ bypass ${key}: ${old.bypass_mode} → ${actor.bypass_mode}`);
|
|
}
|
|
for (const [key, actor] of haveActors) {
|
|
if (!wantActors.has(key)) lines.push(`- bypass ${key} (${actor.bypass_mode})`);
|
|
}
|
|
return lines;
|
|
}
|
|
|
|
function ruleParams(rule) {
|
|
return rule.parameters ? ` ${JSON.stringify(rule.parameters)}` : "";
|
|
}
|
|
|
|
// ───────────────────────────── apply ─────────────────────────────
|
|
|
|
/**
|
|
* Find the repository ruleset with the desired name and create / update / leave it.
|
|
* With dryRun the returned action is what WOULD happen; no write method of gh is called.
|
|
* @param {{gh: object, base?: string, desired: object, dryRun: boolean}} input
|
|
* @returns {Promise<{action: "create"|"update"|"noop", id: number|null, diff: string[]}>}
|
|
*/
|
|
export async function applyRuleset(input) {
|
|
const { gh, desired, dryRun } = input ?? {};
|
|
// A branch ruleset (release kind) must target exactly the base it was asked for; the
|
|
// queue-refs ruleset has no base and keeps the refs of its template.
|
|
if (input?.base !== undefined && input?.base !== null) {
|
|
const expectedRef = `refs/heads/${assertBranchName(input.base)}`;
|
|
if (!desired?.conditions?.ref_name?.include?.includes(expectedRef))
|
|
throw new Error(`desired ruleset does not target ${expectedRef}`);
|
|
} else if (!desired?.conditions?.ref_name?.include?.length) {
|
|
throw new Error("desired ruleset does not target any ref");
|
|
}
|
|
const listed = await gh.listRulesets();
|
|
const sameName = (Array.isArray(listed) ? listed : []).filter(
|
|
(r) =>
|
|
r?.name === desired.name && (r.source_type === undefined || r.source_type === "Repository")
|
|
);
|
|
const wantTarget = desired.target ?? "branch";
|
|
const otherTarget = sameName.filter((r) => (r.target ?? "branch") !== wantTarget);
|
|
if (otherTarget.length)
|
|
throw new Error(
|
|
`repository ruleset ${JSON.stringify(desired.name)} already exists with target ` +
|
|
`${otherTarget.map((r) => `${JSON.stringify(r.target)} (id ${r.id})`).join(", ")}; ` +
|
|
`GitHub refuses a second ruleset with that name: rename or delete it by hand`
|
|
);
|
|
const matches = sameName;
|
|
if (matches.length > 1)
|
|
throw new Error(
|
|
`${matches.length} repository rulesets are named ${JSON.stringify(desired.name)}; ` +
|
|
`resolve the duplicate by hand (ids: ${matches.map((r) => r.id).join(", ")})`
|
|
);
|
|
if (matches.length === 0) {
|
|
const diff = diffRulesets(null, desired);
|
|
if (dryRun) return { action: "create", id: null, diff };
|
|
const created = await gh.createRuleset(desired);
|
|
return { action: "create", id: created?.id ?? null, diff };
|
|
}
|
|
const id = matches[0].id;
|
|
const current = await gh.getRuleset(id);
|
|
const diff = diffRulesets(current, desired);
|
|
if (diff.length === 0) return { action: "noop", id, diff };
|
|
if (!dryRun) await gh.updateRuleset(id, desired);
|
|
return { action: "update", id, diff };
|
|
}
|
|
|
|
// ───────────────────────────── landing path ─────────────────────────────
|
|
|
|
/**
|
|
* Rule types that reject the queue's fast-forward landing push (a merge commit it composed,
|
|
* pushed outside any PR merge, by the App or by the owner) unless the landing actor is a bypass
|
|
* actor of THEIR ruleset: a ruleset's bypass list only covers that ruleset's own rules.
|
|
*/
|
|
export const LANDING_BLOCKING_RULE_TYPES = Object.freeze([
|
|
"pull_request",
|
|
"required_status_checks",
|
|
"update",
|
|
"required_linear_history",
|
|
"required_signatures",
|
|
"merge_queue",
|
|
"required_deployments",
|
|
"workflows",
|
|
"code_scanning",
|
|
]);
|
|
|
|
/** Rule types that never affect a fast-forward push to an existing branch. */
|
|
const LANDING_SAFE_RULE_TYPES = new Set(["deletion", "non_fast_forward", "creation"]);
|
|
|
|
/** Bypass modes that also cover direct pushes ("pull_request" only covers PR merges). */
|
|
const PUSH_BYPASS_MODES = new Set(["always", "exempt"]);
|
|
|
|
/**
|
|
* Bypass actors that cover the owner's token: the repository Admin role or an organization admin,
|
|
* in "always" mode ("pull_request" mode does not cover the direct landing push).
|
|
*/
|
|
const isOwnerBypass = (actor) =>
|
|
String(actor?.bypass_mode ?? "always") === "always" &&
|
|
((actor?.actor_type === "RepositoryRole" &&
|
|
Number(actor.actor_id) === REPOSITORY_ADMIN_ROLE_ID) ||
|
|
actor?.actor_type === "OrganizationAdmin");
|
|
|
|
/**
|
|
* Read the rules GitHub enforces on `base` (GET /repos/{repo}/rules/branches/{base}, all pages,
|
|
* every ruleset that matches it, organization ones included) and report those coming from a ruleset
|
|
* other than `ownRulesetId` that would stop the landing push of `actor`: "app" (the queue's App,
|
|
* which must be an always/exempt Integration bypass actor of that ruleset) or "owner" (the
|
|
* repository owner's token, covered only by an "always" bypass of RepositoryRole 5 or
|
|
* OrganizationAdmin).
|
|
* Example: "Require PR on default branch" (~DEFAULT_BRANCH, pull_request, no bypass) also
|
|
* applies to whichever release branch is the default one.
|
|
* @param {{gh: object, repo: string, base: string, ownRulesetId: number|null,
|
|
* appId: number|null, actor?: "app"|"owner"}} input actor defaults to "app"
|
|
* @returns {Promise<{blockers: string[], warnings: string[]}>} blockers: rule types in
|
|
* LANDING_BLOCKING_RULE_TYPES not bypassed by the landing actor; warnings: other types
|
|
*/
|
|
export async function checkLandingPath(input) {
|
|
const { gh, repo, ownRulesetId = null, appId = null, actor = "app" } = input ?? {};
|
|
if (!LANDING_ACTORS.includes(actor))
|
|
throw new Error(`invalid landing actor: ${JSON.stringify(actor)}`);
|
|
const base = assertBranchName(input?.base);
|
|
if (!REPO_RE.test(String(repo ?? ""))) throw new Error(`invalid repo: ${JSON.stringify(repo)}`);
|
|
const branchPath = base.split("/").map(encodeURIComponent).join("/");
|
|
// Paginated endpoint: follow every Link rel="next" page (paginate uses per_page=100).
|
|
const rules = await gh.paginate(`/repos/${repo}/rules/branches/${branchPath}`);
|
|
const bypassByRuleset = new Map();
|
|
const bypassActorsOf = async (rulesetId) => {
|
|
if (!bypassByRuleset.has(rulesetId)) {
|
|
let actors = null;
|
|
try {
|
|
const ruleset = await gh.getRuleset(rulesetId);
|
|
if (Array.isArray(ruleset?.bypass_actors)) actors = ruleset.bypass_actors;
|
|
} catch {
|
|
actors = null; // not readable with this token: treated as "not bypassed"
|
|
}
|
|
bypassByRuleset.set(rulesetId, actors);
|
|
}
|
|
return bypassByRuleset.get(rulesetId);
|
|
};
|
|
|
|
const blockers = [];
|
|
const warnings = [];
|
|
for (const rule of rules) {
|
|
const type = String(rule?.type);
|
|
const rulesetId = rule?.ruleset_id ?? null;
|
|
if (ownRulesetId !== null && rulesetId === ownRulesetId) continue;
|
|
if (LANDING_SAFE_RULE_TYPES.has(type)) continue;
|
|
const source = `ruleset ${rulesetId} (${rule?.ruleset_source_type ?? "?"} ${rule?.ruleset_source ?? "?"})`;
|
|
let reason;
|
|
if (actor === "app" && appId === null) {
|
|
reason = "cannot tell whether the omni-queue App bypasses it without --app-id";
|
|
} else {
|
|
const actors = await bypassActorsOf(rulesetId);
|
|
if (actors === null) {
|
|
reason = "its bypass actors are not readable with this token";
|
|
} else if (
|
|
actor === "owner"
|
|
? actors.some(isOwnerBypass)
|
|
: actors.some(
|
|
(a) =>
|
|
a?.actor_type === "Integration" &&
|
|
Number(a.actor_id) === appId &&
|
|
PUSH_BYPASS_MODES.has(String(a.bypass_mode ?? "always"))
|
|
)
|
|
) {
|
|
continue;
|
|
} else {
|
|
reason =
|
|
actor === "owner"
|
|
? 'the repository owner is not an "always" bypass actor (RepositoryRole 5 or ' +
|
|
"OrganizationAdmin) of it"
|
|
: `the omni-queue App (Integration ${appId}) is not an "always" bypass actor`;
|
|
}
|
|
}
|
|
const line = `rule ${type} from ${source} on ${base}: ${reason}`;
|
|
if (LANDING_BLOCKING_RULE_TYPES.includes(type)) blockers.push(line);
|
|
else warnings.push(line);
|
|
}
|
|
return { blockers, warnings };
|
|
}
|
|
|
|
// ───────────────────────────── CLI ─────────────────────────────
|
|
|
|
const USAGE = [
|
|
"usage: node scripts/merge-queue/apply-ruleset.mjs --base <branch> [--dry-run]",
|
|
" [--repo <owner/repo>] [--app-id <id>]",
|
|
" node scripts/merge-queue/apply-ruleset.mjs --kind queue-refs [--dry-run]",
|
|
" [--repo <owner/repo>] [--app-id <id>]",
|
|
" --kind release (default): the status door of one release branch;",
|
|
" queue-refs: the ruleset of the queue's own refs (takes no --base)",
|
|
" --base release branch to protect (e.g. release/v3.8.55); required for --kind release",
|
|
" --dry-run print the diff and the REST body; write nothing",
|
|
" --repo owner/repo (default: GITHUB_REPOSITORY)",
|
|
" --app-id numeric id of the omni-queue GitHub App (default: OMNI_QUEUE_APP_ID); required",
|
|
" for a real apply (release: integration_id of the land status; queue-refs: the",
|
|
" only bypass actor)",
|
|
"The land status context and the landing actor come from config/merge-queue/config.json.",
|
|
"A real apply on cheaper-inference/OmniRoute also needs OMNI_QUEUE_ALLOW_PRODUCTION_RULESET=1.",
|
|
"Exit codes: 0 ok, 1 failure (API error, or another ruleset would reject the landing push),",
|
|
"2 usage error or refused.",
|
|
].join("\n");
|
|
|
|
/** True when owner/repo is the production repository (case-insensitive, old name included). */
|
|
export function isProductionRepository(repo) {
|
|
return PRODUCTION_REPOSITORIES.includes(String(repo ?? "").toLowerCase());
|
|
}
|
|
|
|
function resolveToken(env, execImpl) {
|
|
if (env.GITHUB_TOKEN) return env.GITHUB_TOKEN;
|
|
const token = String(execImpl("gh", ["auth", "token"], { encoding: "utf8" }) ?? "").trim();
|
|
if (!token) throw new Error("no GitHub token: set GITHUB_TOKEN or log in with `gh auth login`");
|
|
return token;
|
|
}
|
|
|
|
/**
|
|
* CLI entry. @returns {Promise<number>} exit code (0 ok, 1 failure: API error, or on a real
|
|
* apply another ruleset would reject the landing push; 2 usage / refused)
|
|
* @param {string[]} [argv]
|
|
* @param {Record<string, string|undefined>} [env]
|
|
* @param {{gh?: object, template?: object, config?: {landing: {actor: string,
|
|
* statusContext: string}}, out?: (line: string) => void, err?: (line: string) => void,
|
|
* execFile?: typeof execFileSync}} [deps] test seams
|
|
*/
|
|
export async function main(argv = process.argv.slice(2), env = process.env, deps = {}) {
|
|
const out = deps.out ?? ((line) => console.log(line));
|
|
const err = deps.err ?? ((line) => console.error(line));
|
|
let values;
|
|
try {
|
|
({ values } = parseArgs({
|
|
args: argv,
|
|
strict: true,
|
|
allowPositionals: false,
|
|
options: {
|
|
kind: { type: "string", default: "release" },
|
|
base: { type: "string" },
|
|
"dry-run": { type: "boolean", default: false },
|
|
repo: { type: "string" },
|
|
"app-id": { type: "string" },
|
|
help: { type: "boolean", short: "h", default: false },
|
|
},
|
|
}));
|
|
} catch (error) {
|
|
err(`apply-ruleset: ${error.message}`);
|
|
err(USAGE);
|
|
return 2;
|
|
}
|
|
if (values.help) {
|
|
out(USAGE);
|
|
return 0;
|
|
}
|
|
const dryRun = values["dry-run"];
|
|
const repo = values.repo ?? env.GITHUB_REPOSITORY ?? "";
|
|
const rawAppId = values["app-id"] ?? env.OMNI_QUEUE_APP_ID ?? "";
|
|
const kind = values.kind;
|
|
if (!RULESET_KINDS.includes(kind)) {
|
|
err(`apply-ruleset: --kind must be one of ${RULESET_KINDS.join(", ")} (got ${kind})`);
|
|
err(USAGE);
|
|
return 2;
|
|
}
|
|
if (kind === "queue-refs") {
|
|
if (values.base !== undefined) {
|
|
err("apply-ruleset: --kind queue-refs takes no --base (the queue's refs are fixed)");
|
|
return 2;
|
|
}
|
|
} else {
|
|
if (!values.base) {
|
|
err("apply-ruleset: --base is required");
|
|
err(USAGE);
|
|
return 2;
|
|
}
|
|
try {
|
|
assertBranchName(values.base);
|
|
} catch (error) {
|
|
err(`apply-ruleset: ${error.message}`);
|
|
return 2;
|
|
}
|
|
}
|
|
if (!REPO_RE.test(repo)) {
|
|
err(`apply-ruleset: --repo must be owner/repo (got ${JSON.stringify(repo)})`);
|
|
return 2;
|
|
}
|
|
if (rawAppId !== "" && !APP_ID_RE.test(rawAppId)) {
|
|
err(`apply-ruleset: --app-id must be a positive integer (got ${JSON.stringify(rawAppId)})`);
|
|
return 2;
|
|
}
|
|
const appId = rawAppId === "" ? null : Number(rawAppId);
|
|
if (!dryRun && isProductionRepository(repo) && env.OMNI_QUEUE_ALLOW_PRODUCTION_RULESET !== "1") {
|
|
err(
|
|
`apply-ruleset: refusing to write a ruleset on ${repo} (production). Use --dry-run, or ` +
|
|
"set OMNI_QUEUE_ALLOW_PRODUCTION_RULESET=1 once the owner approved the cut-over."
|
|
);
|
|
return 2;
|
|
}
|
|
if (!dryRun && appId === null) {
|
|
err(
|
|
kind === "queue-refs"
|
|
? "apply-ruleset: a real apply needs --app-id: the App is the only bypass actor of " +
|
|
"the queue's refs, without it nobody could update them"
|
|
: "apply-ruleset: a real apply needs --app-id: it pins the land status to the " +
|
|
"omni-queue App (integration_id), without it any source could write that status"
|
|
);
|
|
return 2;
|
|
}
|
|
|
|
try {
|
|
const templatePath = kind === "queue-refs" ? QUEUE_REFS_TEMPLATE_PATH : DEFAULT_TEMPLATE_PATH;
|
|
const template = deps.template ?? JSON.parse(readFileSync(templatePath, { encoding: "utf8" }));
|
|
// The release ruleset is filled from the queue config; queue-refs needs nothing from it.
|
|
const config = kind === "release" ? (deps.config ?? loadConfig()) : null;
|
|
const desired = buildRuleset(template, {
|
|
base: kind === "release" ? values.base : undefined,
|
|
appId,
|
|
statusContext: config?.landing.statusContext,
|
|
});
|
|
if (appId === null)
|
|
err(
|
|
kind === "queue-refs"
|
|
? "apply-ruleset: no --app-id: the preview leaves out the omni-queue App bypass actor"
|
|
: "apply-ruleset: no --app-id: the preview leaves integration_id unpinned " +
|
|
"(the land status would be accepted from any source)"
|
|
);
|
|
const gh =
|
|
deps.gh ??
|
|
createGitHubClient({
|
|
token: resolveToken(env, deps.execFile ?? execFileSync),
|
|
repository: repo,
|
|
});
|
|
if (!dryRun) {
|
|
// Second gate, before any write: an alias the string check does not know (rename,
|
|
// transfer) resolves, through GitHub's redirect, to the production full_name.
|
|
const info = await gh.request("GET", `/repos/${repo}`);
|
|
const fullName = info?.data?.full_name;
|
|
if (typeof fullName !== "string" || !REPO_RE.test(fullName))
|
|
throw new Error(`could not resolve the repository ${repo} before writing`);
|
|
if (isProductionRepository(fullName) && env.OMNI_QUEUE_ALLOW_PRODUCTION_RULESET !== "1") {
|
|
err(
|
|
`apply-ruleset: refusing to write a ruleset on ${repo}: it resolves to ${fullName} ` +
|
|
"(production). Use --dry-run, or set OMNI_QUEUE_ALLOW_PRODUCTION_RULESET=1 once the " +
|
|
"owner approved the cut-over."
|
|
);
|
|
return 2;
|
|
}
|
|
}
|
|
const result = await applyRuleset({
|
|
gh,
|
|
base: kind === "release" ? values.base : undefined,
|
|
desired,
|
|
dryRun,
|
|
});
|
|
const where = result.id === null ? "" : ` (id ${result.id})`;
|
|
out(`apply-ruleset: ${result.action} ${JSON.stringify(desired.name)} on ${repo}${where}`);
|
|
for (const line of result.diff) out(` ${line}`);
|
|
if (dryRun) {
|
|
out("apply-ruleset: dry-run, nothing was written. REST body:");
|
|
out(JSON.stringify(desired, null, 2));
|
|
}
|
|
|
|
// The queue's refs are not a landing target: only release branches have a landing path.
|
|
if (kind === "queue-refs") return 0;
|
|
|
|
const actor = config.landing.actor;
|
|
let landing;
|
|
try {
|
|
landing = await checkLandingPath({
|
|
gh,
|
|
repo,
|
|
base: values.base,
|
|
ownRulesetId: result.id,
|
|
appId,
|
|
actor,
|
|
});
|
|
} catch (error) {
|
|
const why = error?.message ?? String(error);
|
|
landing = { blockers: [`could not read the rules enforced on ${values.base}: ${why}`] };
|
|
}
|
|
for (const line of landing.warnings ?? []) err(`apply-ruleset: warning: ${line}`);
|
|
for (const line of landing.blockers) {
|
|
err(
|
|
`apply-ruleset: ${dryRun ? "warning" : "error"}: landing push would be rejected: ${line}`
|
|
);
|
|
}
|
|
if (landing.blockers.length) {
|
|
err(
|
|
"apply-ruleset: remove those rulesets (the status door replaces them), with the owner's " +
|
|
"approval, then run this again until it exits 0 (docs/ops/OMNI_QUEUE.md → Ruleset, and " +
|
|
"Cut-over and rollback)."
|
|
);
|
|
if (!dryRun) return 1;
|
|
}
|
|
return 0;
|
|
} catch (error) {
|
|
err(`apply-ruleset: ${error?.message ?? String(error)}`);
|
|
return 1;
|
|
}
|
|
}
|
|
|
|
function invokedDirectly() {
|
|
try {
|
|
return (
|
|
Boolean(process.argv[1]) && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)
|
|
);
|
|
} catch {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
if (invokedDirectly()) {
|
|
main().then((code) => {
|
|
process.exitCode = code;
|
|
});
|
|
}
|