p24-infra Docs

issue-deferral-future-milestone

4 min read

Playbook: Issue Deferral — Future Milestone

What this covers

Deferring a GitHub issue until a specific future date using the defer-until: body line, and understanding how the Future milestone pipeline works end-to-end.

How to defer an issue

Edit the issue body and add this line anywhere:

defer-until: YYYY-MM-DD

Example: to defer issue #999 until 1 July 2026:

  1. Open https://github.com/radieu/p24-infra/issues/999
  2. Click Edit on the issue body
  3. Add a line: defer-until: 2026-07-01
  4. Save

Or via CLI (append to existing body — replace <current body> with the full existing text):

$body = gh issue view 999 --repo radieu/p24-infra --json body --jq '.body'
$body += "`n`ndefer-until: 2026-07-01"
gh issue edit 999 --body $body --repo radieu/p24-infra

The hourly triage will detect this within the hour and move the issue to Future milestone. No labels or milestone changes needed from you.

Automated timeline

TimeEvent
T+0You add defer-until: YYYY-MM-DD to the issue body
T+0 to T+1hHourly triage Phase 0 runs, detects the line, sets Future milestone
00:30 UTC on target dateNightly check Phase 0 promotes: sets Triage milestone, posts a comment
T+0 to T+1h after 00:30 UTCHourly triage Phase 3 spawns a worker; implementation begins

Cancelling a deferral

Remove the defer-until: line from the body (or replace the date with a past date). On the next hourly run, if the issue has no other milestone it will be assigned Triage.

If the issue is already in Future milestone and you remove the line, change the milestone manually to Triage as well — the hourly triage only promotes Future→Triage via the defer-until: line at 00:30 UTC; it will not promote manually-milestoned Future issues.

gh issue edit 999 --milestone "Triage" --repo radieu/p24-infra

Issues in Future without a defer-until: line

Issues #18, #23, #37 and similar are in Future milestone with no defer-until: date. These are permanently deferred items that need manual human action before they can proceed (purchasing WAHA Plus, provisioning a new server, etc.). Both agents ignore them.

To reactivate one: add a defer-until: line with today’s date, or move the milestone manually.

Edge cases

ScenarioOutcome
defer-until: date is todayNext nightly check (00:30 UTC) promotes immediately
defer-until: date is in the past when addedNext nightly check promotes; hourly triage will not
Malformed date (defer-until: soon)Logged as warning, treated as absent, normal Triage assigned
Two defer-until: lines in the bodyFirst match wins (regex Select-Object -First 1)
defer-until: on an In Progress issueHourly triage skips issues that already have a milestone — only affects issues without a milestone

Troubleshooting

Issue stuck in Future after the target date

  1. Confirm the nightly check ran: check dev_r_scheduled_runs in Supabase for a row with job_name='nightly-infra-check' and status='success' on the expected date.
  2. Confirm the defer-until: line is correctly formatted (ISO date, no typos).
  3. Promote manually if needed: gh issue edit 999 --milestone "Triage" --repo radieu/p24-infra

Issue not moving to Future after adding defer-until:

  1. Wait for the next hourly triage (runs at top of every hour on bms-4).
  2. Check the triage log: ssh ubuntu@54.36.123.110 "tail -50 /var/log/hourly-devops-triage.log"
  3. Confirm the issue body contains exactly defer-until: YYYY-MM-DD on its own line (not inside a code block or indented more than expected by the regex).

Regex pattern reference

Both agents use: (?m)^\s*defer-until:\s*(\d{4}-\d{2}-\d{2})\s*$

  • Leading/trailing whitespace on the line is allowed
  • The line must not be inside a fenced code block (the regex has no code-block awareness)
  • The date must be exactly YYYY-MM-DD — no slashes, no words

Prevention / best practice

  • Use defer-until: for issues that are genuinely waiting on a fixed calendar date (scheduled maintenance window, contract start date, dependency release date).
  • Use Future milestone manually (without defer-until:) for items that are indefinitely deferred — WAHA Plus upgrade, new VPS provision, etc.
  • Do not add defer-until: to issues in In Progress or Review — those milestones are respected by both agents; the line will have no effect.

Graph View

Backlinks