Skip to content

Commit a8a13d3

Browse files
cliffhallclaude
andcommitted
ci: guard main so a PR into it brings nothing not already on v2/main
Adds scripts/verify-main-source.mjs and the main-source.yml workflow (pull_request_target into main), which fails unless the PR's head commit is on origin/v2/main. GitHub rulesets cannot restrict a PR's source branch, so this check, made required on main, is what enforces the milestone-merge-only rule in AGENTS.md. Closes modelcontextprotocol#5119 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 9245b93 commit a8a13d3

6 files changed

Lines changed: 379 additions & 5 deletions

File tree

‎.claude/skills/release/SKILL.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -256,12 +256,14 @@ This is the one PR in the repository that targets `main`.
256256
⚠️ **It is merged with "Create a merge commit", never squashed or rebased.** A
257257
squash writes one new commit that `v2/main` does not contain, so the two
258258
branches stop sharing history and the next milestone merge conflicts with
259-
itself.
259+
itself. `main`'s ruleset allows only merge commits, so the other two buttons
260+
are not offered.
260261

261262
⚠️ **Do not click "Update branch" on the merge PR.** GitHub always offers it
262263
here, because `main` always holds commits the merge branch lacks (its own
263264
earlier merge commits), so it does not mean the PR is out of date. Clicking it
264-
merges `main` into the merge branch: the PR gains a commit of its own, `main`
265+
merges `main` into the merge branch: the PR gains a commit of its own (which
266+
fails the required **Source is v2/main** check, `main-source.yml`), `main`
265267
receives two merge commits, and the branch head is no longer the commit the
266268
ledger names. If it was clicked, put the branch back on its head from before
267269
the click: the update merge's **first parent**, which is the commit the ledger

‎.github/workflows/main-source.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# A pull request into `main` brings nothing that is not already on `v2/main`
2+
# (#5119). `main` only ever receives a milestone's merge PR, a pure merge of
3+
# `v2/main`; GitHub rulesets cannot restrict a PR's source branch, so this
4+
# check, required by the `main` ruleset, is what does. The rule and why it is
5+
# on the head commit rather than the branch name are in
6+
# `scripts/verify-main-source.mjs`.
7+
#
8+
# On `pull_request_target`, unlike dco.yml: it runs `main`'s copy of this
9+
# workflow and of the script, so a PR cannot edit the guard into passing. That
10+
# is safe here because nothing from the PR runs: the checkout is `main`, and
11+
# the PR's head is only fetched as git objects for `git merge-base` to read.
12+
# Never add a step that checks out, installs or runs the PR's code.
13+
# `edited` is there so retargeting a PR onto `main` runs the check.
14+
on:
15+
pull_request_target:
16+
types: [opened, synchronize, reopened, edited]
17+
branches: [main]
18+
19+
# Read-only, and handed no secret, so this job holds no credential and stays
20+
# outside the SHA-pin rule (`verify:action-pins`).
21+
permissions:
22+
contents: read
23+
24+
concurrency:
25+
group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
26+
cancel-in-progress: true
27+
28+
jobs:
29+
main-source:
30+
timeout-minutes: 5
31+
name: Source is v2/main
32+
runs-on: ubuntu-latest
33+
steps:
34+
# The base branch (`main`), which `pull_request_target` checks out by
35+
# default; never the PR's ref.
36+
- uses: actions/checkout@v6
37+
with:
38+
persist-credentials: false
39+
40+
# The PR's head and `v2/main`, as objects only. A fork PR's head is
41+
# reachable here through `refs/pull/<n>/head`. Full history, so
42+
# `git merge-base` can walk both.
43+
- name: Fetch the PR head and v2/main
44+
env:
45+
PR_NUMBER: ${{ github.event.pull_request.number }}
46+
run: |
47+
git fetch --no-tags --unshallow origin \
48+
"+refs/heads/v2/main:refs/remotes/origin/v2/main" \
49+
"+refs/pull/${PR_NUMBER}/head:refs/remotes/pr/head"
50+
51+
- uses: actions/setup-node@v7
52+
with:
53+
node-version: 22
54+
55+
# Node built-ins and git only, so no `npm ci`.
56+
- name: Check the head is already on v2/main
57+
env:
58+
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
59+
run: node scripts/verify-main-source.mjs --head "$HEAD_SHA"

‎AGENTS.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ servers/
6262
├── .github/workflows/ typescript.yml, python.yml (per-package CI), release.yml (publishes on a GitHub Release),
6363
│ version-packages.yml (the changesets PR), prepare-python-release.yml (the CalVer PR),
6464
│ claude.yml (@claude mentions), everything-mcp-diff.yml (everything's interface diff on PRs),
65+
│ main-source.yml (a PR into main must bring nothing that is not on v2/main),
6566
│ and the scheduled sweeps that file issues: dependency-refresh.yml, dependabot-alerts.yml, sdk-watch.yml
6667
├── .github/ISSUE_TEMPLATE/ Bug and feature issue forms; config.yml routes security and new servers away
6768
├── .github/pull_request_template.md The "issues, not PRs" banner that turns outside PRs away
@@ -153,6 +154,10 @@ diagnosing a red stage is the `pre-push-gate` skill.
153154
publish artifact into an empty directory and boots it, which needs the
154155
network. `release.yml` runs it before anything publishes, and the `release`
155156
skill runs it by hand for the ledger.
157+
- **`verify-main-source` is not a gate stage either.** It applies only to a
158+
pull request into `main` (see the merge PR exception under
159+
[Contributing](#contributing)), and every local push targets a v2 branch.
160+
`main-source.yml` runs it.
156161
- **`local:*` scripts never run in a workflow, and every CI job declares
157162
`timeout-minutes`.** The script tests enforce both
158163
(`scripts/lib/workflow-gate.mjs`). A check added to CI is added to
@@ -353,8 +358,10 @@ holds for a maintainer's own one-line fix as much as for a feature.
353358
default branch a closing keyword would close that issue at merge, before
354359
anything is published. The release issue is closed by hand once the Release
355360
is published. In place of the checklist it links the **release ledger**. It
356-
is merged with a merge commit, never squashed. The flow is the `release`
357-
skill.
361+
is merged with a merge commit, never squashed. Both are enforced on `main`:
362+
its ruleset allows only merge commits, and requires the **Source is
363+
v2/main** check (`main-source.yml`), which fails a PR whose head carries
364+
any commit not already on `v2/main`. The flow is the `release` skill.
358365
- **Exception: the two version PRs that automation opens.** Each changes
359366
version metadata only, so neither answers the PR checklist below, and each
360367
is tied to its milestone's **release issue** rather than to an issue of its

‎docs/quality-gate.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ out; everything else points here.
1313
| --- | --- | --- | --- |
1414
| Inner loop | `npm run validate -w src/<server>`, `npm run validate:py -- <server>` | Your machine | While iterating on one server |
1515
| Pre-push gate | `npm run local:gate` | Your machine, under a lease | Before every push |
16-
| CI | `.github/workflows/typescript.yml`, `python.yml`, `everything-mcp-diff.yml`; `dco.yml` | GitHub, on every push and pull request (`everything-mcp-diff.yml`: when `everything` or what builds it changes); `dco.yml` on pull requests only | Before merge |
16+
| CI | `.github/workflows/typescript.yml`, `python.yml`, `everything-mcp-diff.yml`; `dco.yml`; `main-source.yml` | GitHub, on every push and pull request (`everything-mcp-diff.yml`: when `everything` or what builds it changes); `dco.yml` on pull requests only; `main-source.yml` on pull requests into `main` only, and not mirrored by a gate stage, since no local push targets `main` | Before merge |
1717

1818
**`npm run local:gate` runs every check CI runs.** CI splits the same checks
1919
into parallel jobs on a fresh install; the gate runs them in sequence on your

‎scripts/verify-main-source.mjs‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
#!/usr/bin/env node
2+
// Guard: a pull request into `main` brings nothing that is not already on
3+
// `v2/main` (#5119).
4+
//
5+
// `main` is the release line. The one PR that may target it is a milestone's
6+
// merge PR, a pure merge of `v2/main` (AGENTS.md, "Contributing"). GitHub
7+
// rulesets can require a PR and its approvals, but cannot say where a PR comes
8+
// from, so before this guard a PR from any branch could merge into `main`.
9+
//
10+
// The rule is on the COMMIT, not the branch name: the PR's head must be an
11+
// ancestor of the source (`origin/v2/main`), or the source itself. The
12+
// `release` skill opens the merge PR from `v2/chore/<N>-release-<milestone>`,
13+
// a branch pushed from `origin/v2/main`, so a check on the head's name would
14+
// refuse the one PR the rule exists to allow. An ancestor rather than only an
15+
// equal commit, because `v2/main` keeps moving while the merge PR is open, and
16+
// the PR is still a pure merge of what it was opened with.
17+
//
18+
// CI runs it from `main-source.yml` on `pull_request_target`, which runs
19+
// `main`'s copy of the workflow and of this script, so a PR cannot edit the
20+
// guard into passing. The PR's head is only fetched as git objects; none of
21+
// its code runs. It is not a `local:gate` stage: every local push targets a
22+
// v2 branch, where the rule does not apply.
23+
24+
import { spawnSync } from "node:child_process";
25+
import path from "node:path";
26+
import { fileURLToPath, pathToFileURL } from "node:url";
27+
28+
/** The branch every commit on `main` must already be on. */
29+
export const DEFAULT_SOURCE = "origin/v2/main";
30+
31+
/** How many of the offending commits the report lists. */
32+
export const MAX_LISTED = 20;
33+
34+
/**
35+
* Pure: `--head <rev>` (required) and `--source <rev>`.
36+
*
37+
* @param {string[]} argv
38+
*/
39+
export function parseArgs(argv) {
40+
const opts = { source: DEFAULT_SOURCE, head: "" };
41+
for (let i = 0; i < argv.length; i++) {
42+
const flag = argv[i];
43+
if (flag !== "--source" && flag !== "--head")
44+
throw new Error(`unknown argument: ${flag}`);
45+
const value = argv[++i];
46+
if (!value) throw new Error(`${flag} needs a revision`);
47+
opts[flag.slice(2)] = value;
48+
}
49+
if (!opts.head) throw new Error("--head is required");
50+
return opts;
51+
}
52+
53+
/**
54+
* Pure: the report for a head that carries commits the source does not.
55+
*
56+
* @param {{ source: string, head: string, commits: string[] }} args
57+
* `commits` is `git log --oneline <source>..<head>`, one per entry
58+
*/
59+
export function formatReport({ source, head, commits }) {
60+
const n = commits.length;
61+
const listed = commits.slice(0, MAX_LISTED).map((c) => ` ${c}`);
62+
if (n > MAX_LISTED) listed.push(` … and ${n - MAX_LISTED} more`);
63+
return [
64+
`verify:main-source: ${head} carries ${n} commit${n === 1 ? "" : "s"} that ${source} does not:`,
65+
...listed,
66+
"",
67+
"A pull request into `main` must be a pure merge of `v2/main`: its head",
68+
"is a commit already on `v2/main`. Land the change on `v2/main` through",
69+
"its own PR, and it reaches `main` with the next milestone merge (the",
70+
"`release` skill).",
71+
].join("\n");
72+
}
73+
74+
function git(args, cwd) {
75+
const r = spawnSync("git", args, { cwd, encoding: "utf8" });
76+
if (r.error) throw r.error;
77+
return r;
78+
}
79+
80+
/**
81+
* Check that `head` is `source` or an ancestor of it, in the repository at
82+
* `cwd`.
83+
*
84+
* @returns {{ code: number, output: string }}
85+
*/
86+
export function verifyMainSource({ source, head, cwd }) {
87+
for (const rev of [source, head]) {
88+
if (
89+
git(["rev-parse", "--verify", "--quiet", `${rev}^{commit}`], cwd).status
90+
)
91+
return {
92+
code: 1,
93+
output:
94+
`verify:main-source: cannot resolve ${rev}.` +
95+
(rev === DEFAULT_SOURCE
96+
? " Fetch it (`git fetch origin v2/main`), or name another source with --source."
97+
: ""),
98+
};
99+
}
100+
const anc = git(["merge-base", "--is-ancestor", head, source], cwd);
101+
if (anc.status === 0)
102+
return {
103+
code: 0,
104+
output: `verify:main-source: ${head} is on ${source}; nothing else comes with it.`,
105+
};
106+
if (anc.status !== 1)
107+
return {
108+
code: 1,
109+
output: `verify:main-source: git merge-base failed:\n${anc.stderr}`,
110+
};
111+
const log = git(
112+
["log", "--oneline", "--no-decorate", `${source}..${head}`],
113+
cwd,
114+
);
115+
if (log.status)
116+
return {
117+
code: 1,
118+
output: `verify:main-source: git log failed:\n${log.stderr}`,
119+
};
120+
const commits = log.stdout.split("\n").filter((l) => l.trim() !== "");
121+
return { code: 1, output: formatReport({ source, head, commits }) };
122+
}
123+
124+
if (
125+
process.argv[1] &&
126+
import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
127+
) {
128+
let opts;
129+
try {
130+
opts = parseArgs(process.argv.slice(2));
131+
} catch (e) {
132+
console.error(`verify:main-source: ${e.message}`);
133+
process.exit(2);
134+
}
135+
const repoRoot = path.resolve(
136+
path.dirname(fileURLToPath(import.meta.url)),
137+
"..",
138+
);
139+
const { code, output } = verifyMainSource({ ...opts, cwd: repoRoot });
140+
(code === 0 ? console.log : console.error)(output);
141+
process.exit(code);
142+
}

0 commit comments

Comments
 (0)