Skip to content

Commit 8e3a18a

Browse files
cliffhallclaude
andcommitted
docs(skills): close the advisory fork's PR before publishing; keep follow-up write-ups on the card
GitHub refuses to publish an advisory while its private fork has an open PR, and publishing deletes the fork. The security-advisory skill now closes the fork's PR once its head is on v2/main, adds both checks to the pre-publish list, and keeps a follow-up card's write-up on the card so step 6 can still read it after publication. Closes modelcontextprotocol#5251 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 82acf2a commit 8e3a18a

1 file changed

Lines changed: 67 additions & 15 deletions

File tree

  • .claude/skills/security-advisory

‎.claude/skills/security-advisory/SKILL.md‎

Lines changed: 67 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ labels, tracked by the draft card).
4444
| 2 | **Verify the claim**: which server, and does the code belong to it or to an SDK? | Judgment |
4545
| 3 | Valid and ours → **accept** (`triage` → `draft`); otherwise close with a reason | **Human only** |
4646
| 4 | Create the **private fork**, fix and review there | Mechanical |
47-
| 5 | Merge to `v2/main`, milestone merge, **release**, then **publish** | **Human only** |
47+
| 5 | Merge to `v2/main`, milestone merge, **release**, close the fork's PR, then **publish** | **Human only** (closing the fork's PR is mechanical) |
4848
| 6 | **After publication**, convert the draft card into a public issue | Mechanical |
4949

5050
There is **one release line**. Every fix lands on `v2/main` and ships through
@@ -275,12 +275,15 @@ body nobody will read again.
275275
- **Body:** the same link-and-triage-only rule as step 1. Its lines, in order:
276276
- `**Advisory:** <html_url>` on the first line.
277277
- `Follow-up to the fix for this advisory. Convert to an issue only once the advisory is published.`
278-
- A link to the write-up.
279278
- The `Priority <level> (provisional, <YYYY-MM-DD>)` line.
280-
- **The write-up lives in the private fork**, where only the advisory's
281-
collaborators can read it. Draft it as the public issue it will become
282-
(problem, options, acceptance criteria), and post it as a `COMMENT` review on
283-
the fork's PR, since the fork refuses issue comments (see the API table).
279+
- The write-up, under a `## Write-up` heading.
280+
- **The write-up lives on the card itself**, never only in the private fork.
281+
⚠️ **Publishing an advisory deletes its temporary private fork**, and every
282+
review and comment in it with it, while step 6 needs the write-up _after_
283+
publication. Draft it as the public issue it will become (problem, options,
284+
acceptance criteria). The card is read by everyone with board access (step
285+
1), so the write-up describes the remaining work and leaves the reproduction
286+
and any proof of concept in the private advisory.
284287
- **Status `Todo`** when a maintainer asked for the follow-up: the advisory is
285288
already accepted, and asking for the work approves it. Otherwise it goes in
286289
`Incoming`. Score its Priority with step 1's table, using the severity of the
@@ -325,9 +328,59 @@ stop there.
325328
⚠️ **Publishing is irreversible and human-only.** It makes the advisory public,
326329
with no undo. Same rule as accepting: recommend, never perform.
327330

328-
**Before publishing, check what publishing will show**, because a published
329-
advisory is what users and advisory tooling (Dependabot, `npm audit`,
330-
`pip-audit`) remediate from:
331+
#### Close the fork's PR once its fix is on `v2/main`
332+
333+
**GitHub will not publish an advisory while its private fork has an open pull
334+
request.** The advisory page says "you must merge or close outstanding pull
335+
requests" and **Publish advisory** stays disabled. The fix reaches `v2/main`
336+
through a PR in this repository, so the fork's own PR is left open with
337+
nothing still to merge, and blocks publication until someone closes it.
338+
339+
Closing it is mechanical and reversible (a PR can be reopened), and it neither
340+
closes nor publishes the advisory. Close a PR **only once its head is on
341+
`origin/v2/main`**:
342+
343+
```sh
344+
GHSA=<GHSA_ID>
345+
FORK=$(gh api repos/modelcontextprotocol/servers/security-advisories/$GHSA \
346+
--jq '.private_fork.full_name // empty') || FORK=
347+
[ -n "$FORK" ] || echo "no private fork for $GHSA (or the lookup failed)" >&2
348+
git fetch origin v2/main
349+
for pr in $( [ -n "$FORK" ] && gh api --paginate "repos/$FORK/pulls?state=open" \
350+
--jq '.[] | "\(.number):\(.head.sha)"'); do
351+
n=${pr%%:*}; sha=${pr#*:}
352+
# The fork's commits are not in this clone until fetched; an unknown SHA
353+
# fails --is-ancestor, which leaves the PR open: the safe direction.
354+
git fetch -q "https://github.com/$FORK.git" "$sha" 2>/dev/null
355+
if git merge-base --is-ancestor "$sha" origin/v2/main; then
356+
gh api -X PATCH "repos/$FORK/pulls/$n" -f state=closed --jq '"closed \(.html_url)"'
357+
else
358+
echo "$FORK#$n: head $sha is NOT on v2/main; left open" >&2
359+
fi
360+
sleep 1
361+
done
362+
```
363+
364+
- ⚠️ **A PR whose head is not on `v2/main` stays open.** Its fix has not
365+
shipped, so the advisory is not ready to publish; find out what is missing
366+
rather than closing the PR to unblock the button.
367+
- **Close it without a comment.** The forks have issues disabled, so a PR
368+
comment (the issue-comments endpoint) returns `404`.
369+
370+
#### Before publishing, check what publishing will show
371+
372+
A published advisory is what users and advisory tooling (Dependabot,
373+
`npm audit`, `pip-audit`) remediate from, and publishing deletes the private
374+
fork, so check each of these first:
375+
376+
- **No open PR in the private fork.** Run the close recipe above. Found now,
377+
it is a recipe; found at the button, it is a disabled button and no reason
378+
given beyond "outstanding pull requests".
379+
- **Nothing that matters lives only in the fork.** Publishing deletes it.
380+
Review findings worth keeping, a residual-exposure note, a follow-up's
381+
write-up: copy each onto the advisory (if it belongs in what is published) or
382+
onto the advisory's draft card (if it is tracking), before the button is
383+
pressed.
331384

332385
- **The affected product**: ecosystem (`npm` or `pip`) and package name, as
333386
published (`@modelcontextprotocol/server-filesystem`, `mcp-server-git`).
@@ -345,9 +398,6 @@ advisory is what users and advisory tooling (Dependabot, `npm audit`,
345398
- **What the fix leaves open**, if the advisory has a follow-up card. Say which
346399
platforms or cases are still exposed, so a user who upgrades does not believe
347400
they are fully covered.
348-
- **The follow-up's write-up, copied out of the fork** before publishing. Once
349-
the advisory is published, don't count on the temporary fork, or on access to
350-
it, surviving.
351401

352402
### 6. After publication, convert the card into public tracking
353403

@@ -379,8 +429,9 @@ work has not shipped:
379429

380430
1. Retitle it `[GHSA-xxxx-yyyy-zzzz follow-up] - <summary>`.
381431
2. Convert it.
382-
3. Replace the body's triage lines with the write-up copied out of the fork
383-
(step 5), linking the now-public advisory.
432+
3. Replace the body's triage lines with the card's own `## Write-up` section
433+
(step 4), linking the now-public advisory. The fork is gone by now, so the
434+
card is the only copy.
384435
4. Apply `/issue-create`'s labels. A card already past `Incoming` also takes
385436
the milestone the follow-up is planned for, not the one the fix shipped in.
386437
A card still in `Incoming` stays unmilestoned: once it is an issue the
@@ -397,7 +448,8 @@ work has not shipped:
397448
| Listing | `GET repos/{owner}/{repo}/security-advisories`, 30 per page, so always `--paginate` |
398449
| Private fork | `POST …/security-advisories/{ghsa_id}/forks` → `202`, a private repo `servers-ghsa-xxxx-yyyy-zzzz` (lowercase) in the org; exact name in `.private_fork.full_name` |
399450
| Fork idempotency | Read `.private_fork` first; the POST creates, it does not probe |
400-
| Fork deletion | Needs the `delete_repo` OAuth scope, which a default `gh` token lacks |
451+
| Fork deletion | Needs the `delete_repo` OAuth scope, which a default `gh` token lacks. **Publishing deletes the fork** on its own: the repo returns `404` and `.private_fork` reads `null` |
452+
| Publishing blocked | An open PR in the private fork disables **Publish advisory**; close it once its head is on `v2/main` (step 5) |
401453
| Comments | **No API at all**, REST or GraphQL; UI-only |
402454
| Fork PR comments | Issue comments (`gh pr comment`, `issues/N/comments`) are refused and `…/comments/{id}/replies` returns `404`; reply in a thread with `POST pulls/N/comments -F in_reply_to=<id>`, and post a PR-level summary as a `COMMENT` review |
403455
| Credits | `credits_detailed` on the advisory; a private report carries the reporter's credit (`type` `reporter`, `state` `pending` or `accepted`) from submission |

0 commit comments

Comments
 (0)