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:
- File the deferred finding as an issue with the
security::deferredlabel (plus a general security label) and the target milestone, for planning. - The pre-release audit and
scripts/release.shboth runscripts/check-security-deferred.sh, which blocks on any issue that has ever carriedsecurity::deferred, in any milestone and any state, unless it is resolved. - 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.
The label
Section titled “The label”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.
What the check does with it
Section titled “What the check does with it”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-releaseskill’s Step 1.6 runs it for every audit type; only afullaudit gates/releaseon the result. scripts/release.shre-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=1bypasses 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.
Cleared deferrals
Section titled “Cleared deferrals”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:
- A merged MR closed it. GitLab: the close event carries
source_merge_request_id. GitHub: theClosedEvent’s closer is a merged pull request (read over GraphQL). The line readsRESOLVED (fixed by merged MR, source_merge_request_id=N)orRESOLVED (fixed by merged PR #N). A close by a commit (Closes #Nin 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 readsRESOLVED (fixed by merged MR !N via commit <sha>)orRESOLVED (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 onmainbeing protected (push: nobody), so that every commit on it arrived through a merged MR. - 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. - 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.
Accepted-risk note
Section titled “Accepted-risk note”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-byis@plus[A-Za-z0-9_.-]+;reasonis non-blank with no;.expiresis a real calendar date and the last field on the line (twoexpiresfields never match).- A note whose
expiresdate 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-byhandle, and the expiry so the release owner can still read it before tagging. - The check fails closed: if the forge CLI (
glab/gh) orjqis 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.
Who may accept a deferral
Section titled “Who may accept a deferral”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 putCloses #NorRelated to #Nin the MR description. - GitHub: put
Closes #Nor a mention of#Nin 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’slabel: nullevent 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 #Nresolves the deferral. On a project wheremainis 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 printedRESOLVED (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, andSECURITY_DEFERRED_BOT_HANDLES. An agent running under a human’s own token looks like that human, including to the Maintainer check.SECURITY_DEFERRED_BOT_HANDLESis 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
Zor±HH:MMoffset is applied and fractional seconds are dropped; a timestamp in any other form makes the exit “not observable”.
Verdict script and its self-test
Section titled “Verdict script and its self-test”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.
Confidential issues
Section titled “Confidential issues”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.