Troubleshooting GitQueue

Understand how GitQueue works internally, how it handles Checks/Approval/Freshness outcomes, and how to diagnose common issues.

How GitQueue Works Internally

Webhook-Driven Architecture

GitQueue responds to GitHub webhook events in real-time. When you comment, push code, GitHub updates PR state, or reviews are submitted, GitHub sends webhooks that trigger GitQueue's processing logic.

Idempotent by design

Duplicate webhook deliveries must not create duplicate merge lane rows or duplicate overview comments. GitQueue keeps reusing the same top-level overview comment for each PR.

Key Webhook Events

Event Type	When Triggered
issue_comment	When you post a new /gitqueue command comment
pull_request	On PR opens, closes, and status changes
pull_request_review	When reviews are submitted

Periodic Reconciliation

In addition to webhooks, GitQueue runs periodic reconciliation to ensure consistency. This catches any missed events and keeps the queue state accurate.

Why reconciliation matters: If a webhook is dropped or delayed, periodic reconciliation ensures GitQueue eventually processes all queued PRs correctly.

GitQueue ignores bot-authored comments and edited PR comments for command execution. Only newly created user comments are parsed.

Gate Evaluation

Before merging a PR, GitQueue evaluates exactly three gates. Checks, Approval, and Freshness all need to pass before a merge can proceed.

The Three Gates

1. Checks

The Checks gate comes from GitHub merge state plus required check contexts. It can resolve to pending, pass, warn, or fail.

Note: GitQueue treats clean, unstable, and has_hooks as passing-style outcomes, while behind becomes warn.

2. Approval

The Approval gate is derived from GitHub review state. It passes when GitHub reports approval or otherwise has no blocking review decision.

Note: If approval is not passing, the PR can still be added to lowest.

3. Freshness

Freshness comes from GitHub REST pull request data and compare API data. It handles stale, pending, and failing branch states.

Recoverable: Freshness warn triggers an automatic branch update and a retry on the next cycle.

Failure Classification & Handling

GitQueue classifies failures into two categories: recoverable and irrecoverable. This determines how GitQueue responds to each failure type.

Recoverable Failures

Failures that GitQueue can automatically fix by updating the branch. The PR stays in its current position.

Recovery Actions

Condition	Action
Branch Out of Date	Update branch using GitHub's "Update branch" feature, stop processing for current cycle, re-evaluate in next cycle
Mergeable Not Clean + Branch Out of Date	Treat as recoverable because stale branch state takes precedence, update branch first, then re-evaluate
Branch Freshness Unknown	Keep PR in lane and retry in a later cycle after freshness data can be resolved

Important: Recoverable failures don't move the PR to the end of its lane. GitQueue waits for the next cycle to retry.

Deferred update recovery: If a branch update request is deferred or rejected, GitQueue re-checks freshness in the next cycle and continues normal processing once the branch is confirmed fresh.

Irrecoverable Failures

Failures that require manual intervention. GitQueue moves the PR to the end of its lane and continues processing the next PR.

Irrecoverable Conditions

Condition	Action
Merge Conflicts	Move to end, requires manual resolution
Approval No Longer Passed	Move to end, needs reviews
Mergeable Failed on Fresh Branch	Move to end, needs a fresh fix

Important: Moving to the end doesn't remove the PR from its merge lane. Fix the issue and the PR will be retried when it reaches the front again.

Processing Within Lanes

Understanding how GitQueue processes PRs after irrecoverable failures is crucial for predicting merge timing.

When a PR fails irrecoverably, GitQueue moves it to the end of its current lane
GitQueue continues to the next PR in the same lane
If all PRs in the lane have been attempted, move to the next lower-priority lane
Cycle tracking prevents infinite loops by tracking which PRs were attempted this cycle

No lane blocking: A failing PR never blocks its lane. GitQueue skips it and moves to the next PR, giving every PR a chance to merge each cycle.

Common Issues & Solutions

PR Not Merging

If your PR is stuck in a merge lane:

Check the overview comment for gate status
Verify Checks and Approval are still passing
Confirm Freshness is not stale, pending, or failing
Look at the activity log on the status page

PR Moved to End

If GitQueue moved your PR to the end of its lane:

Check the overview comment for the failure reason
Resolve failing checks or merge conflicts if present
Get new approvals if they were revoked
Push a fix if a fresh-branch gate is still failing
The PR will be retried when it reaches the front again

Can't Add to Queue

If you can't add a PR to a merge lane:

Ensure the PR targets the default branch
Make sure it's not a draft
Check you have the required permissions for that lane
Verify Checks, Approval, and Freshness are pass or warn for non-lowest lanes (or use lowest while the PR is still pending)
Check if the repository is blocked

Branch Update Taking Long

Branch updates pause the current cycle until GitHub state settles:

GitQueue keeps the PR in the same lane position
GitQueue retries on the next processing trigger
Monitor the branch update and PR state on GitHub
Pending mergeability or unknown freshness will also defer work

Understanding Activity Logs

GitQueue maintains an activity log for each PR, visible on the web status page and in the PR overview comment. This log shows the latest GitQueue events in a compact audit trail.

Activity Log Features

Automatic Deduplication

If GitQueue evaluates a PR multiple times with the same result, it updates the newest matching row's timestamp instead of creating duplicate entries.

Timestamp Updates

When results are deduplicated, the activity timestamp updates to show the latest evaluation time.

State Change Tracking

New activity entries are created when gate states, outcomes, or reasons change.

How to Read Activity Logs

Check the most recent entry for current status
Look for patterns (e.g., repeated failures)
Timestamps show when each recorded event occurred
Each entry records timestamp, actor, and message

Configuration, Billing & Timing

Configuration Refresh Timing

GitQueue refreshes repository configuration (.github/gitqueue.yml) only at specific times to avoid excessive API calls.

When Config is Refreshed

During periodic reconciliation runs
When commits are pushed to the default branch

If you update .github/gitqueue.yml, changes will be picked up on the next periodic sync or when you push to the default branch.

Account Activation and Entitlements

Queue behavior also depends on billing state. Repositories are active only when the app is installed, the account is active, and the repository is within the plan entitlement set.

• New installations start in an active 1-month free trial if there is no active paid Marketplace plan yet
• After trial expiry, accounts without an active paid plan move to hold and webhook-triggered queue work is skipped
• If installed repositories exceed the plan allowance, only the first entitled repositories ordered by full name stay active
• Each entitled repository also has an active processing PR cap; enqueue above that cap is rejected with informational feedback

Idempotent Operations

All GitQueue operations are idempotent, meaning they can be safely retried without causing unintended side effects.

Why this matters: If a webhook is duplicated or processing is interrupted, GitQueue safely handles retries without duplicate lane rows, duplicate overview comments, or corrupted state.