Skip to content
Skills Library
DevOps & cloud · Learning & explanation

merge-queue

/merge-queue

This skill should be used when working with GitHub merge queues and branch protection — queue semantics, required checks, strict status checks, auto-merge, and why a merge is blocked.

Repository
claude ↗
Licence
MIT
Last repository change
22.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

This skill should be used when working with GitHub merge queues and branch protection — queue semantics, required checks, strict status checks, auto-merge, and why a merge is blocked.

Original author description

This skill should be used when working with GitHub merge queues and branch protection — queue semantics, required checks, strict status checks, auto-merge, and why a merge is blocked.

How it works

  1. Strict status checks
  2. What a merge queue actually does
  3. mergeablestate values
  4. Protection settings that matter
  5. Diagnosing a blocked merge
  6. Never
  7. See also
Original SKILL.md headings · 89 lines, 618 words
SKILL.md preview
---
name: merge-queue
description: This skill should be used when working with GitHub merge queues and branch protection — queue semantics, required checks, strict status checks, auto-merge, and why a merge is blocked.
version: 1.0.0
trigger_phrases: [merge queue, branch protection, required checks, auto-merge, cannot merge, mergeable state]
categories: [github, merge, policy, ci]
author: github-orchestrator
created: 2026-08-11
updated: 2026-08-11
---

# Merge Queue & Branch Protection

## Strict status checks

"Require branches to be up to date before merging" is the difference between a
green check that means something and one that does not.

Without it, a PR can merge on a green run against a base from three days ago —
the checks passed against code that no longer exists. With it, the head must be
current, so every merge is gated on a run against the real post-merge state.

The cost is rebase churn on busy repositories. That is what merge queues solve.

## What a merge queue actually does

The queue builds a **speculative merge** of your PR on top of the queue ahead of
it, runs checks against that combination, and merges only if it passes. This
gives strict-check correctness without every author manually rebasing.

Consequences worth knowing:

- Your PR's own green checks are not the queue's checks. The queue re-runs
  against the speculative merge.
- A PR can be **ejected** from the queue when the speculative merge fails —
  even though nothing about your PR changed. The conflict is with what landed
  ahead of you.
- Repeated ejection for the same check means a genuine interaction, not bad
  luck. After two ejections on the same check, pull the PR out and triage rather
  than re-queueing a third time.

Prefer `enable_pr_auto_merge` over merging directly in queue repositories, so
the queue owns ordering.

## `mergeable_state` values

| Value | Meaning |
| --- | --- |
| `clean` | Ready |
| `blocked` | A required check is failing or a required review is missing |
| `behind` | Head is behind the base and strict checks are required |
| `dirty` | Merge conflict |
| `unstable` | A non-required check is failing — mergeable, but look at why |
| `draft` | Draft PR |
| `has_hooks` | Clean, with a pre-receive hook that may still reject |

`unstable` is the one that gets misread. It means mergeable; it does not mean
fine.

## Protection settings that matter

| Setting | Why |
| --- | --- |
| Required status checks, **strict** | Green means green against the current base |
| Dismiss stale approvals on push | Otherwise an approval survives a rewrite of the diff it approved |
| Require conversation resolution | Unresolved blocking feedback cannot merge |
| Restrict force push and deletion | |
| `enforce_admins` | A bypass available to admins is a bypass |
| Required linear history | Forces squash or rebase; simplifies revert |

`enforce_admins: false` is the most common silent gap — the protection looks
complete on the settings page and is bypassable by anyone with admin.

## Diagnosing a blocked merge

Check in this order and stop at the first hit:

1. Is a required check failing at the **current** head sha?
2. Is a required check *missing* — never reported, not failed? A renamed job is
   a required check that will never arrive.
3. Is the review quorum unmet, or is a `CHANGES_REQUESTED` outstanding?
4. Are there unresolved conversations?
5. Is the head behind with strict checks required?
6. Is there a conflict?
7. Is the PR a draft?

Point 2 is the one that wastes the most time — a required check that was renamed
in the workflow leaves the PR waiting forever for a job that no longer exists.

## Never

Never merge with a red required check. Never use admin bypass. Never re-run a
check to turn it green without classifying why it was red.

## See also

- `stacked-prs` — landing dependent PRs through a queue
- `github-orchestration` — the gate list enforced before merging

Versions

RepositoryScoreLicence
This page · TheLobbi/claude90MIT
alienfast/claude100MIT
nexadevapp/nexa-claude-skills-marketplace100Apache-2.0
jacob-balslev/skill-graph100Apache-2.0

Database snapshot: 13.11.2026 · package version cf798d82e73d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100graphite-setup
    Configure a GitHub repository for Graphite — branch protection, merge queue, CI triggers, and stack-aware CI optimizations. Use when the user is onboarding a repo to Graphite, mentions Graphite branch protection / required checks / signed commits / merge queue, sees CI failing…
  • 100archestra-merge-queue
    Use when asked to add an Archestra PR to the merge queue, monitor it through merge, or diagnose and repair merge-group CI failures. Own the requested PR until merged or an actionable blocker; opening a PR alone does not start this workflow.
  • 100graphite-merge-queue
    Operate the Graphite Merge Queue — enqueue PRs via label, dequeue, monitor queue status, and reason about stacked-PR queueing. Use when the user mentions Graphite merge queue, "merge when ready", queueing a PR, dequeueing, fast-track, the merge-queue label, "enqueue", "the…
  • 90setup
    /factory:setup. Install Factory in the current repository on the user's consent: write .github/workflows/factory.yml from the Action's template, walk the Factory GitHub App creation, and apply the merge queue, branch protection, labels and Project board; or set up local mode on…
  • 100cloud-tasks-queue-setup
    Configure cloud tasks queue setup operations. Auto-activating skill for GCP Skills. Triggers on: cloud tasks queue setup, cloud tasks queue setup Part of the GCP Skills skill category. Use when working with cloud tasks queue setup functionality. Trigger with phrases like "cloud…
  • 100cloudflare-queues
    This skill should be used when the user asks to \"set up Cloudflare Queues\", \"create a message queue\", \"implement queue consumer\", \"process background jobs\", \"configure queue retry logic\", \"publish messages to queue\", \"implement dead letter queue\", or encountering…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.