134 lines
6.5 KiB
Markdown
134 lines
6.5 KiB
Markdown
---
|
|
status: draft
|
|
system: integrations
|
|
created: 2026-08-24
|
|
owners:
|
|
- Kandev
|
|
---
|
|
# GitHub PR Merge Queue Recovery Requirements
|
|
|
|
## Overview
|
|
|
|
GitHub can remove a pull request from a merge queue after a merge-group check
|
|
fails or a conflict appears. Kandev shows active queue membership, but it does
|
|
not retain the removal event or repair the pull request.
|
|
|
|
Queue-aware automation extends the existing per-PR auto-fix and auto-merge
|
|
controls. It does not add a separate queue-recovery preference.
|
|
|
|
## Terminology
|
|
|
|
- **Queue attempt:** One queue entry for one pull-request head commit.
|
|
- **Queue removal:** A GitHub `RemovedFromMergeQueueEvent` for an open pull
|
|
request.
|
|
- **Actionable removal:** A queue removal with a failed check, a timed-out
|
|
check, or a merge conflict.
|
|
|
|
## Requirements
|
|
|
|
### REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-001: Queue removal observation
|
|
|
|
**Intent:** Kandev must retain a queue removal after the active queue entry
|
|
disappears. This record lets automation respond after a short queue attempt.
|
|
|
|
#### Acceptance criteria
|
|
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-001.1:** When GitHub reports
|
|
a queue removal, Kandev shall store its provider event ID, time, reason, and
|
|
available commit identity.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-001.2:** When Kandev misses
|
|
the active queue entry, a later poll shall still detect the latest queue
|
|
removal from the pull-request timeline.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-001.3:** When Kandev
|
|
restarts, the last observed queue attempt and removal shall remain available
|
|
for deduplication and status display.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-001.4:** When a queue-aware
|
|
read fails, Kandev shall preserve the last complete queue-recovery state.
|
|
|
|
### REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002: Queue failure auto-fix
|
|
|
|
**Intent:** Auto-fix must send actionable merge-queue failures to the linked
|
|
task agent without sending the same removal more than once.
|
|
|
|
#### Acceptance criteria
|
|
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.1:** When auto-fix is
|
|
enabled and a new actionable removal appears, Kandev shall send or queue one
|
|
auto-fix prompt for that removal.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.2:** The prompt shall
|
|
include the queue-removal reason and conflict state. It shall include failed
|
|
check names and links only when Kandev has an exact commit identity for those
|
|
checks.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.3:** The removal event ID
|
|
shall participate in the auto-fix checkpoint. Repeated polls shall not send
|
|
the same removal again.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.4:** A queue-recovery
|
|
prompt shall consume one of the existing 10 auto-fix rounds for that linked
|
|
pull request.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.5:** A manual or unknown
|
|
removal without failed-check or conflict evidence shall not start auto-fix.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.6:** When the task is
|
|
busy, the queue-recovery prompt shall use the existing durable auto-fix queue
|
|
and coalescing rules.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.7:** When a user enables
|
|
auto-fix after Kandev retained an unhandled actionable removal with durable
|
|
queue-attempt evidence for the current head, the next evaluation shall send
|
|
or queue one repair prompt.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.8:** Kandev shall not
|
|
treat the removal event's commit as a merge-group commit unless GitHub
|
|
identifies it as such.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-002.9:** When Kandev first
|
|
observes an actionable removal after the active queue entry disappears, it
|
|
shall start auto-fix only when durable evidence from an attempted or adopted
|
|
queue entry matches the current pull-request head. A passive removal-only
|
|
baseline is not sufficient provenance, so Kandev shall fail closed when that
|
|
evidence is unavailable.
|
|
|
|
### REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003: Safe automatic requeue
|
|
|
|
**Intent:** Auto-merge must requeue a repaired pull request without creating a
|
|
same-head retry loop or reversing an intentional queue removal.
|
|
|
|
#### Acceptance criteria
|
|
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.1:** When GitHub accepts
|
|
a queue attempt, Kandev shall record the attempted pull-request head commit.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.2:** When GitHub removes
|
|
that queue attempt, auto-merge shall not requeue the same head commit.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.3:** When the head commit
|
|
changes and the existing merge gates pass, auto-merge shall submit one new
|
|
queue-aware merge request.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.4:** A user or agent can
|
|
repair the pull request when auto-fix is disabled. A later eligible head
|
|
commit shall still re-arm auto-merge.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.5:** When both controls
|
|
are enabled, each actionable removal can start one repair round. A new
|
|
eligible head can then start one queue attempt.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.6:** Kandev shall use
|
|
GitHub's queue-aware default merge action. It shall not bypass repository
|
|
rules or choose direct merge instead of the required queue.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.7:** When a user enables
|
|
auto-merge while the pull request already has an active queue entry, Kandev
|
|
shall adopt that entry and head as the current attempt. It shall not submit a
|
|
duplicate merge request.
|
|
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-RECOVERY-003.8:** When a user enables
|
|
auto-merge after a queue removal, Kandev shall keep the same-head guard. It
|
|
shall wait for a new eligible head instead of reversing the removal.
|
|
|
|
## Related requirements
|
|
|
|
- [GitHub PR Merge Queue](github-pr-merge-queue.md)
|
|
`REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002` owns attempt reservation,
|
|
explicit retry, and stale auto-merge error reconciliation.
|
|
- [Task PR Automation Controls](../../ui/requirements/ci-pr-automation.md)
|
|
- [Merge Queue Recovery Controls](../../ui/requirements/ci-pr-merge-queue-recovery-controls.md)
|
|
|
|
## Out of scope
|
|
|
|
- Webhook ingestion for merge-group events.
|
|
- Automatic retry of a flaky queue failure without a new pull-request head.
|
|
- Editing branch protection, rulesets, or workflow files from the controls.
|
|
- Removing a pull request from the queue.
|
|
- Coordinated recovery and queue ordering for stacked pull requests.
|
|
- GitLab merge-request behavior.
|