Skip to content

Deferred security follow-ups

The big picture: A security finding noticed during review is sometimes filed as a follow-up issue instead of fixed on the branch. The security::deferred label makes that follow-up visible to the release process instead of letting it sit open while a tag ships with the gap still in it.

Why it matters: A review agent or a human reviewer can find a real gap, the author can file a tracked follow-up in good faith, and without this label nothing connects that issue back to the release that is about to ship past it.

How it works:

  1. File the deferred finding as an issue with the security::deferred label (plus a general security label) and the target milestone, for planning.
  2. The pre-release audit and scripts/release.sh both run scripts/check-security-deferred.sh, which blocks on any issue that has ever carried security::deferred, in any milestone and any state, unless it is resolved.
  3. An open issue that still carries the label is resolved only by a valid accepted-risk comment (below), written by a Maintainer who is neither the author of a linked MR nor anyone who applied the label, with an expiry date. Removing the label or closing the issue does not hide it: a cleared deferral is resolved only when a merged MR closed it, when the person who closed or unlabeled it is an eligible Maintainer (the same rule), or when it carries a valid accepted-risk comment (Cleared deferrals). The other way out for a GA tag is RELEASE_SKIP_SECURITY_DEFERRED_CHECK=1.

security::deferred marks an issue filed as a deferred follow-up from a review — by the security-review or rbac-check agent, or by a human. It is deliberately narrow: do not put it on tracking issues, dependency advisories waiting on an upstream fix, or general hardening ideas that were never found during a specific review.

The label name is configurable: scripts/check-security-deferred.sh and scripts/release.sh both read SECURITY_DEFERRED_LABEL, defaulting to security::deferred, the same convention scripts/wt uses for WT_LOCK_LABEL.

The label must exist. The check looks the label up before anything else and fails closed (could not run: label security::deferred not found) when it is missing: deleted, renamed or never created. Otherwise every deferral would drop out silently. Create it once per project, glab label create --name 'security::deferred' on GitLab or gh label create 'security::deferred' on GitHub; make doctor warns while it is missing.

scripts/check-security-deferred.sh lists every issue in the project, in every state, and keeps the ones that carry security::deferred now or that the forge reports the label was ever added to. An open issue still carrying the label is a blocker unless it carries a valid, unexpired accepted-risk note. Any other one is a cleared deferral, judged as described in Cleared deferrals. Issues that never carried the label are not counted.

Scope: ever deferred, judged by current state. Once an issue has carried the label it stays in scope, whatever happens to it later. Why this and not a window since the last release tag: docs/adr/0005-security-deferred-scope-is-state-based.md.

Milestone scope: all issues, any milestone. The check does not filter by milestone. An unfixed gap is already on the default branch and ships with whatever gets tagged next, regardless of which milestone the issue happens to sit on — so an issue moved to a later milestone, or left open under an already-closed one, must not drop out of the check. A deliberate deferral to a later release is expressed with an accepted-risk note, not by moving the milestone.

Where it runs:

  • The pre-release skill’s Step 1.6 runs it for every audit type; only a full audit gates /release on the result.
  • scripts/release.sh re-runs the identical query immediately before tagging, but GA tags only — a pre-release tag (alpha/beta/rc) prints a note and is not gated, since a pre-release audit between now and the GA tag will still catch it. RELEASE_SKIP_SECURITY_DEFERRED_CHECK=1 bypasses the pre-tag gate deliberately; it still prints the per-issue list to stderr as a trace and never silently changes the outcome.

Both call the one implementation, so the query cannot diverge between the two call sites.

What can block a GA tag. Beyond an open issue with no note, scripts/release.sh also blocks a GA tag when the label does not exist, when a deferral was cleared (closed, or unlabeled, including by a scoped-label swap) by someone who may not clear it, when how it was cleared is not observable, and for an issue that: (1) carries its only accepted-risk note in the issue description (description notes no longer count); (2) has no linked MR; (3) has no label-add event the forge still reports (an imported or migrated issue, or one whose label was deleted and recreated); (4) has a note from an author who is not a verified Maintainer, or whose note was edited. In a project with a single maintainer, if that person’s token applied the label or authored the linked MR, acceptance is impossible: the only ways through are a merged MR that closes the issue, or RELEASE_SKIP_SECURITY_DEFERRED_CHECK=1.

A deferral is cleared when its issue is closed, or is open but no longer carries the label (someone removed it, or on GitLab added another scoped security:: label, which removes this one; that the forge records the swapper as the actor of the removal is assumed, not verified live). The check judges the exit: the latest close if the issue is closed, otherwise the latest removal of the label, and only an exit after the latest time the label was added (a fix that predates a re-deferral does not count). In order, the issue is resolved when:

  1. A merged MR closed it. GitLab: the close event carries source_merge_request_id. GitHub: the ClosedEvent’s closer is a merged pull request (read over GraphQL). The line reads RESOLVED (fixed by merged MR, source_merge_request_id=N) or RESOLVED (fixed by merged PR #N). A close by a commit (Closes #N in a commit message rather than the MR description) counts too when that commit belongs to a merged MR: GitLab records only the commit (source_commit), so the check looks up the commit’s merge requests; GitHub reports the commit as the closer, with its associated pull requests. The line then reads RESOLVED (fixed by merged MR !N via commit <sha>) or RESOLVED (fixed by merged PR #N via commit <sha>). A commit with no merged MR or pull request is judged by who closed the issue, and a failed commit lookup is a blocker. This relies on main being protected (push: nobody), so that every commit on it arrived through a merged MR.
  2. An eligible person closed or unlabeled it: someone who passes the same rule as an accepted-risk note’s author (Who may accept a deferral), a verified human Maintainer who neither applied the label nor authored a linked MR and is not a bot. The line reads RESOLVED (cleared by @m, a verified human maintainer) and is printed on every run, so the release owner keeps seeing it.
  3. It carries a valid accepted-risk comment, judged exactly as for an open issue.

Otherwise it blocks: BLOCKER (deferral cleared by @x via close; x may not clear a deferral) (or via label removal). When the exit cannot be seen (no close or removal after the latest add, an unparseable timestamp, a deleted actor, a GitLab event with no user id) and no note accepts it, the line is BLOCKER (how the deferral was cleared is not observable). A cleared issue’s line carries state=closed or state=open-unlabeled after the milestone.

The latest exit governs. If a Reporter closed a deferral, an eligible Maintainer repairs it by reopening and closing the issue, provided at least one MR is linked to the issue (the linked-MR author must be excludable, so an issue with no linked MR blocks with no linked MR observable; a hand-cleared old deferral often has none, so link the MR first). A later close by someone ineligible undoes an earlier good one, including a fix. Re-adding the label to an open issue puts it back on the open-issue path. An accepted-risk note is a repair that does not last: it expires within a year, and the closed issue then blocks again until a fresh note is posted.

In a project with a single maintainer who applied the label, that maintainer is on the deny list, so only a fixing MR (or RELEASE_SKIP_SECURITY_DEFERRED_CHECK=1) clears the deferral.

The final line reads checked N issue(s) across all milestones (scanned T, C cleared): N in-scope issues, T issues listed, C of the N cleared.

One line, in a comment on the issue (a note in the issue description is ignored: anyone with edit rights can append to a description, and it is attributed to the issue author, so it has no trustworthy author):

Accepted risk: accepted-by: @<maintainer>; reason: <why shipping is acceptable>; expires: YYYY-MM-DD
  • Fields appear in exactly this order, separated by ; .
  • accepted-by is @ plus [A-Za-z0-9_.-]+; reason is non-blank with no ;.
  • expires is a real calendar date and the last field on the line (two expires fields never match).
  • A note whose expires date is in the past does not count; the issue is a blocker again. An expiry more than 1 year out is rejected too (expiry too far out).
  • Any ONE valid line accepts the issue, subject to “Who may accept a deferral” below. The check’s output prints the note’s author, the accepted-by handle, and the expiry so the release owner can still read it before tagging.
  • The check fails closed: if the forge CLI (glab/gh) or jq is missing, or the API query fails, it reports a blocker rather than “0 issues” — nothing backstops this check the way a later job backstops some others.
  • Add the note only on a maintainer’s explicit decision. Fixing the issue (closing it with the merged MR that fixes it) is the normal way out; the note is for knowingly shipping with the gap.

The person accepting the risk must be a human Maintainer, distinct from the author of any linked MR and from everyone who applied the security::deferred label, and not a bot. The issue’s filer is not excluded unless they also applied the label or authored a linked MR. A note counts only if all of these hold, as observed from the forge:

Rule How it is checked
The note’s author is the accepted-by handle The comment’s author. Writing accepted-by: @someone in another person’s name does not count.
The comment was never edited updated_at must equal created_at; an edited comment, or one missing either timestamp, is ignored. An edited comment keeps its original author, so a person with edit rights could otherwise rewrite someone else’s comment into an acceptance. After a legitimate edit, post a fresh comment.
Not the author of any linked MR GitLab: related merge requests of the issue. GitHub: pull requests that cross-reference the issue in its timeline.
Not anyone who applied the deferral The actor of every label event adding the label, not only the last. On GitLab the actor of an add event whose label was later deleted (label: null) is excluded too, but an add event for a deleted label does NOT count as this label having been observed. No add event for this label, or an actor that comes back null, is a blocker; a deleted account is usually reassigned to ghost by the forge, which then simply sits on the deny list.
A Maintainer GitLab: access_level >= 40 from members/all/:user_id. GitHub: role_name of admin or maintain from collaborators/:login/permission. A 404, an error, a missing field or a non-object answer means “not a Maintainer” and the note is rejected.
Human, not a bot GitLab: users/:id must report bot: false (note authors carry no bot flag, so this is looked up). GitHub: the comment author’s type must not be Bot. On both forges, never a handle ending in -bot or _bot, starting project_<n>_bot, group_<n>_bot or service_account_, or listed in SECURITY_DEFERRED_BOT_HANDLES (space or comma separated).

Handle comparison is case-insensitive. The failure message names the rule that blocked. The possible blockers: accepted-by is not the note author, accepted-by is the MR author or the identity that applied the deferral, accepted-by is a bot or agent identity, accepted-by is not a verified human maintainer, expiry too far out; max 1 year, no linked MR observable, label applier or linked-MR author not observable (a null applier or MR author), and a plain BLOCKER for a missing, expired or malformed note. When edited notes were ignored the line ends (N edited note(s) ignored; post a fresh comment).

Linking the MR. The check needs at least one linked MR, or it blocks (no linked MR observable). How to link depends on the forge:

  • GitLab: an MR counts when it is a related merge request of the issue. Mention the MR (!N) in the issue description or a comment, or put Closes #N or Related to #N in the MR description.
  • GitHub: put Closes #N or a mention of #N in the PR description; the link is the cross-reference event that lands on the issue. A mention of the PR from the issue does not create it, and a mention from another issue does not count.

Known limits. The check does not claim more than it enforces:

  • Clearing is judged from forge events, so what the forge does not report is invisible. Deleting an issue removes it and its events from both forges’ APIs, so a deleted deferral drops out (both forges restrict deletion to their highest project roles; not re-verified here). On GitHub two lower-privilege actions also remove a deferral from the listing: someone with write access can transfer the issue to another repository, and someone with triage access can convert it to a discussion; either way it is no longer in repos/:owner/:repo/issues, and the check cannot see it. (On GitLab, assumed and not verified live: a moved or promoted issue leaves the original behind, closed, and the mover is judged as its closer.) An imported or migrated issue with no label events is in scope only while it still carries the label. Whether an issue converted to another work-item type (GitLab) still appears in the issues API is not verified.
  • A deleted label fails the whole check closed until it is recreated. Recreating it does not restore old events: on GitLab an add event for a deleted label comes back as label: null, which does not put an issue in scope, so a deferral whose label was deleted, recreated and not re-applied drops out. Anyone allowed to manage labels can do this in two steps (delete, recreate), so a recreated label is worth a look before a GA tag: compare its age on the forge’s labels page with the deferrals you expect to see. The original applier’s label: null event is still excluded from accepting (over-exclusion, the safe direction: it can also exclude the actor of a different deleted label). A rename that changes only the case is handled: the label, the issue’s labels and the events are all matched ignoring case.
  • “Fixed by a merged MR” means any merged MR that closed the issue, directly or through one of its commits. The check does not verify that the MR changed the code the finding is about, which branch it merged into, or who authored or merged it; anyone who can merge an MR carrying Closes #N resolves the deferral. On a project where main is not protected, a commit pushed directly can still close the issue: it then has no merged MR and is judged by who closed it. On GitHub it also does not check that the closing pull request belongs to this repository. The release owner reads the printed RESOLVED (fixed by …) lines.
  • “MR author” means the author of ANY linked MR. The check excludes every MR the forge links to the issue, but cannot tell which one is the MR the finding was deferred from. If that MR does not link to the issue and some other MR does, the real author is not excluded and can accept. On GitLab, anyone who can comment on the issue or edit its description can add or remove linked MRs, so the linked-MR set is editable.
  • “Human” is checked only through the forge’s bot flag (GitLab users/:id, GitHub user type), the handle shape, and SECURITY_DEFERRED_BOT_HANDLES. An agent running under a human’s own token looks like that human, including to the Maintainer check. SECURITY_DEFERRED_BOT_HANDLES is read from the shell environment and is not stored in the repo; where agents share the owner’s token, listing that handle also blocks the owner.
  • A role is read when the check runs, not when the note was written or the issue closed.
  • With a single maintainer, acceptance is impossible whenever that person’s token applied the label or authored a linked MR; the only escape for a GA tag is RELEASE_SKIP_SECURITY_DEFERRED_CHECK=1 (or a merged MR that closes the issue). The same token cannot clear the deferral by closing or unlabeling it either.
  • Events and links are taken as the forge reports them. The release owner must still read the printed note author and accepted-by.
  • Failed lookups fail closed, so a flaky forge API shows up as a blocker, never as an acceptance. That includes the label-event lookup for an issue that never carried the label: until the events are read the check cannot know the issue is out of scope.
  • The check reads every issue’s label events, one request per issue in the project (plus, per cleared issue, its close events and its notes and linked MRs), so it is slow on a large tracker and exposed to rate limits; a rate-limited request is a blocker like any other failed lookup. Measured on Blueprint’s own GitLab project (2026-10-20): 6 minutes 1 second for 226 issues, about 1.6 seconds per issue. Run it in the background, or with a timeout well above that, when a tool would otherwise cut it off.
  • Timestamps are compared in UTC. A Z or ±HH:MM offset is applied and fractional seconds are dropped; a timestamp in any other form makes the exit “not observable”.

The accepted-risk verdict (the note’s regex, plus the calendar and expiry check) is scripts/security-deferred-verdict.sh, not inline shell — it is committed, self-tested code rather than an untested markdown snippet. It reads candidate lines (<author>|Accepted risk: ...) on stdin, with TODAY and CAP (latest allowed expiry) from the environment, and prints ACCEPTED note-by=... accepted-by=... expires=... (exit 0) or BLOCKER / BLOCKER (<reason>) (exit 1), with the reasons listed above. It is POSIX sh/awk, so it runs on macOS (BSD awk) and Linux.

The excluded handles arrive as SD_DENY (MR authors, label appliers), SD_BOTS and SD_NOTMAINT (handles that could not be verified as Maintainers), all computed by the check from the forge.

sh scripts/security-deferred-verdict.sh --self-test covers valid, expired, blank accepted-by / reason, impossible dates, two expires fields, a ; in reason, no note, multiple lines, month/day ranges, leap-year rules, and the who-may-accept rule (note author must equal accepted-by; MR author, label applier, bot and non-Maintainer handles are rejected, each with a positive control).

bash scripts/check-security-deferred.sh --self-test covers the query and loop around the verdict script, against a stubbed forge CLI (no network) — including both glab and gh shapes, since the check is forge-neutral, and the identity rules end to end: MR author, every label applier (a first applier is still excluded after a second one re-adds the label), each documented bot handle shape, a configured bot handle, a mismatched note author, a Developer or Reporter (rejected) against a Maintainer or Owner (accepted) on each forge, a 404 or malformed role answer, an edited or timestamp-less comment, a description note, no linked MR, no label event, a deleted account, and failed events/MR/role queries must block. For cleared deferrals it covers a label removed or an issue closed by a Reporter, by the applier, by a linked-MR author or by a bot (each blocks), the same by an eligible Maintainer and a close by a merged MR (each resolves), a scoped-label swap, a fixing close that predates a re-deferral, the latest exit governing in both directions, a valid and an expired note, an unobservable exit (no event, a null actor, a missing id, an unparseable time), failed state-event and label-event queries, a missing label, never-labeled issues (not counted), a re-deferred issue returning to the open path, a case-only label rename, unreadable event and issue answers, a close by a commit of a merged (or unmerged, or no) MR and a failed commit lookup, timestamps with UTC offsets, an unmerged pull request as closer, an eligible exit with no linked MR, and per-issue events across a mixed listing. The cases marked [main] in the script were confirmed to pass (return 0) against the check as it stood before macrodream/blueprint#213.

Forge-neutral, like the rest of the harness

Section titled “Forge-neutral, like the rest of the harness”

The check picks glab or gh from the origin remote’s host, overridable with WT_FORGE — the same convention scripts/wt and scripts/check-issue-collision.sh use. GitLab issues carry a confidential flag the check reports; GitHub has no per-issue equivalent, so it prints confidential=n/a under gh.

A deferred security issue filed as confidential (GitLab) is still visible to the maintainer token the check runs as. Any report that leaves the session — MR text, a public issue, docs — cites the issue number only, never the title or body.