kandev/docs/specs/integrations/requirements/github-pr-merge-queue.md

---
status: active
system: integrations
created: 2026-08-17
owners:
  - Kandev
---

# GitHub PR Merge Queue Requirements

## Overview

The integration system owns GitHub merge actions and merge-queue state. Users
must be able to merge an eligible pull request without leaving Kandev. Kandev
must show whether GitHub merged the pull request or added it to a merge queue.

The same provider contract owns automatic merge attempts from linked tasks.
Kandev must bind each attempt to the pull-request state that passed its readiness gates.

## Terminology

- **Readiness signature:** A stable identity for one pull-request head and its
  observed merge gates.
- **Automatic attempt:** A merge request that Kandev starts after auto-merge
  observes a ready pull request.
- **Explicit retry:** One user-requested evaluation of a prior failed automatic
  attempt for one linked pull request.

## Requirements

### REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001: GitHub PR Merge Queue

**Intent:** Users can complete an eligible GitHub pull request through the
repository's configured merge path. They can then observe its current queue
state from the existing pull-request surfaces.

#### Acceptance criteria

- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.1:** When GitHub requires a merge queue for an eligible pull request, Kandev shall expose the existing merge action.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.2:** When the user activates the merge action, Kandev shall let GitHub select a direct merge or the configured queue.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.3:** When GitHub accepts the request, Kandev shall report whether GitHub merged or queued the pull request.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.4:** After GitHub accepts the request, Kandev shall prevent repeated submission until the pull-request state refreshes.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.5:** When a pull request has an active queue entry, Kandev shall use GitHub's merge-queue color, `#966600`.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.6:** When states compete, Kandev shall prioritize terminal states, then queue state, then other non-terminal states.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.7:** When GitHub supplies queue metadata, Kandev shall show localized state, position, and available estimate data.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.8:** When an estimate is less than one minute, Kandev shall use a localized sub-minute label. Larger estimates shall round up.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.9:** When GitHub omits an estimate, Kandev shall show state and position without invented estimate data.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.10:** When GitHub supplies an unknown non-empty state, Kandev shall show generic localized copy instead of the raw value.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.11:** When a refresh cannot observe queue membership, Kandev shall preserve the last confirmed entry. An authoritative empty or terminal state shall clear it.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.12:** When a pull request is a draft, conflicted, failing checks, awaiting checks, missing reviews, or has requested changes, Kandev shall hide the merge action.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.13:** When GitHub rejects a merge request, Kandev shall show the error, preserve state, and leave the action available for retry.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-001.14:** When users view queue state on desktop or mobile, Kandev shall provide the same outcome without hover-dependent controls or horizontal page overflow.

### REQ-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002: Reliable automatic merge attempts

**Intent:** Automatic merge must act on the reviewed pull-request head without
repeating an unchanged side effect or leaving obsolete errors after GitHub accepts it.

#### Acceptance criteria

- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.1:** When Kandev starts an
  automatic merge, the request shall require the non-empty head SHA from the
  fresh readiness snapshot. A different current head shall not merge.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.2:** Before Kandev calls GitHub,
  it shall durably reserve the per-PR readiness signature and attempted head.
  A restart or unchanged later poll shall not repeat that automatic request.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.3:** When a readiness gate or the
  pull-request head changes, Kandev shall permit one new automatic attempt only
  after every current gate passes.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.4:** When the user retries a
  failed automatic merge, Kandev shall reevaluate only the named linked pull
  request. The retry shall not bypass readiness, head binding, repository
  scope, permissions, or GitHub policy.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.5:** When GitHub reports an
  active queue entry or a merged pull request, Kandev shall reconcile the
  attempt as accepted and clear only its obsolete auto-merge error.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.6:** When Kandev cannot persist
  the automatic attempt reservation, it shall not call GitHub and shall show a
  retryable per-PR error.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.7:** While GitHub reports a
  pending asynchronous merge, Kandev shall request status no more than once per
  second and shall stop when the bounded operation context ends.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.8:** When an upgrade finds a
  recognized legacy auto-merge error, Kandev shall classify it so a later queue
  or merged observation can clear it.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.9:** When users view an
  auto-merge error on desktop or mobile, they shall have the same explicit
  retry action. A load error shall keep a separate state-refresh action.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.10:** When auto-fix is enabled
  for at least one active linked pull request, the task-row pull-request icon
  shall show a yellow indicator at its top-left. When auto-merge is enabled,
  it shall show a purple indicator at its top-right. Both indicators can
  appear together.
- **AC-INTEGRATIONS-GITHUB-PR-MERGE-QUEUE-002.11:** When a user examines the
  task-row pull-request icon with a pointer, keyboard, or touch input, Kandev
  shall identify the enabled automation settings and the active pull requests
  that use them. Merged and closed pull requests shall not produce active
  automation indicators.

## Out of scope

- Displaying or navigating the complete merge queue.
- Removing a pull request from the merge queue.
- Selecting between direct merge and queue entry when GitHub permits both.
- Changing the stored value or default of Kandev's independent CI auto-merge setting.
- Changing automation settings from the task-row pull-request indicator.
- Adding merge-queue behavior for GitLab merge requests.

## System design

- [GitHub PR Merge Queue System Design](../system-design/github-pr-merge-queue.md)

## Implementation plans

- [Automatic merge reliability plan](../../../plans/github-auto-merge-reliability/plan.md)
- [Sidebar automation indicators plan](../../../plans/github-sidebar-automation-indicators/plan.md)
- [Queue-status visibility plan](../../../plans/github-pr-merge-queue-status/plan.md)
- [Original queue-aware merge action plan](../../../plans/github-pr-merge-queue/plan.md)