Merge a Pull Request

Why is this a Capability MLE? Incorporating a pull request's changes into its target branch is a distinct, determinable outcome from opening it — a PR can be open for weeks without ever being merged, and merging is subject to entirely separate authorization and policy gates.

What does this example teach? Paired with Open a pull request, it demonstrates why Manage pull requests would be the wrong, too-broad single capability (see the comparison on the examples index) — and, on its own, that capability meaning can stay simple and stable while realization complexity grows substantially: draft-PR gating, required reviews, status checks, five distinct merge methods, and UI/CLI/REST/auto-merge/async-merge/merge-queue realizations all sit underneath one unchanged meaning: "incorporate proposed changes into the target branch."

Evidence status: extracted from GitHub's own public documentation, independently blind-audited for conformance and factual accuracy — the framework's flagship real-world example.

Identity and core meaning

NameMerge a pull request

DefinitionThe ability for an authorized actor to integrate the changes proposed by an already-open, non-draft pull request into its target branch, subject to the repository's own merge policies, producing a definitive merged/closed outcome or an identifiable failure reason.

Capability purposeEnable the changes proposed by an open pull request to be incorporated into the target branch, using one of a small set of documented merge strategies, once the repository's own conditions for merging are satisfied.

Meaningful outcomeThe pull request becomes merged (target branch updated, merged: true), or the attempt is rejected with an identifiable reason.

IncludesChoosing the merge strategy; optionally overriding the commit title/message; optionally requiring a head-SHA match; the immediate success/failure outcome.

ExcludesOpening the pull request; reviewing/approving it; closing it without merging; enabling/disabling auto-merge; checking if it's already merged; updating its branch; configuring branch protection; merging a draft PR.

Tagsnotification-triggering — merging is documented as triggering notifications and secondary rate limiting; chosen over network-touching, which would add nothing beyond this capability's own API/UI exposure on a hosted product.

Interaction Contract MLE

Actor: A repository member holding the Write, Maintain, or Admin role — Read and Triage roles cannot merge.
Command / intent: Integrate the pull request's proposed commits into its base branch using a specified or repository-permitted merge method.
Policies / invariants: Write/Maintain/Admin access required; draft PRs cannot be merged; required reviews and status checks (if configured) must be satisfied; required linear history restricts merge method to squash/rebase; admin bypass applies by default; a supplied sha must match the current head commit.
Transition: Open, non-draft pull request (mergeable state permitting) → merged pull request; also becomes closed as a result.
Result: 200 with merged: true, or 403/404/405/409/422 with a distinct documented meaning.
Events / effects: pull_request webhook event, action: closed; the merged field distinguishes a merge from a plain close; notifications to other users/systems.
Unknowns: The full mergeable_state enumeration; whether any default merge_method applies; the exact 405 vs. 422 boundary.

Rules and defaults

Rules / invariants

Only Write/Maintain/Admin access (or explicit bypass rights) may merge a pull request.
A draft pull request cannot be merged.
Required reviews and status checks, if configured, must be satisfied before a merge can succeed.
Required linear history, if configured, restricts the merge method to squash or rebase.

Recommended defaults

By default, branch-protection restrictions don't apply to admins or an explicit bypass role — GitHub's own stated default, not a universal rule.
Deleting the head branch after merge is a documented convenience, not a requirement.

Optional: operational realization

Execution modesoftware-primary for the REST/GraphQL/CLI/web-UI paths and the merge queue; unknown for the asynchronous merge REST mechanism's internals.

ExposureUI, API (REST and GraphQL), tool (CLI).

Known realization	Confirmed via
github.com web UI	Merge button/dropdown with three merge-method choices; "You can't merge a draft pull request."
GitHub REST API	`PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge` — full parameter/response/status-code set, including the exact 200/403/404/405/409/422 wording.
GitHub GraphQL API	Existence confirmed via cross-reference only; specific mutation not independently retrievable.
GitHub CLI	`gh pr merge [flags]` — merge-strategy, auto-merge, admin-bypass, and delete-branch flags confirmed.
GitHub merge queue	Confirmed, GitHub-native automated realization: "GitHub will merge all these changes into the base_branch once the checks required by the branch protections of base_branch pass" — not just a sequencing mechanism.
Third-party bots / automation	Not confirmed for this capability — Dependabot pull requests are documented as manually reviewed and merged by the user (distinguish from GitHub's own merge queue, above).

Unknown / unresolved

The full set of mergeable_state values.
Whether the webhook closed payload's own description ties merged to that action.
Whether a default merge_method is applied when omitted.
The precise conditions distinguishing 405 from 422.

See the full unresolved questions document for the complete list shared with Open a pull request.

Related MLEs by Dimension

Traceability only, evidence-bound like the rest of this extraction. Four dimensions are omitted, each for a stated reason: Interaction/Behaviour (self-referential to this capability's own sole contract, above), Backend/Execution and Data/Information (GitHub documents the public REST/GraphQL/webhook contract, not its internal implementation or data model beyond the public resource schema), and Verification (this CRD's own operational realization already states tests aren't documented by GitHub as part of this material). Unlike Open a pull request, Communication is included here — GitHub's documented merge response gives an exact, quoted success message to ground it on, which the create response does not. This asymmetry reflects what GitHub actually publishes, not an inconsistency between the two extractions.

Dimension	Relationship	Ref	Notes
Business/Domain	constrains	Branch-protection policy consumption (required reviews, status checks, linear history, admin-bypass default)	Already stated under Rules; referenced here.
UX/Experience	supports	Merge button; disabled/blocked control state when branch-protection conditions are unmet
Communication	defines	Merge Success Confirmation	See below.
Frontend/Interface	supports	Three-way merge-method dropdown (merge commit / squash / rebase)
API/Interoperability	implements	`PUT /repos/{owner}/{repo}/pulls/{pull_number}/merge`; merge-async pair; GraphQL (existence only); `gh pr merge`	Already stated under known realizations.
Agentic	supports	GitHub merge queue	Already stated above — a platform-native automated realization, not a skill/tool in the agent sense.
Operations	supports	Secondary rate-limiting risk on rapid merges; branch-protection gating

Communication MLE: Merge Success Confirmation

Purpose: Confirm to the actor or calling system that requested the merge that it completed, and identify the resulting commit.
Trigger: The merge succeeds (200 response).
Audience: The actor or system that called the merge operation.
Required meaning: The merge succeeded; a resulting merge commit SHA now exists.
Possible realizations: REST API JSON response field message, confirmed. Whether the web UI or CLI paths surface equivalent wording is unknown/unresolved — not confirmed in the material fetched, and not assumed to match by inference.
Example copy: "Pull Request successfully merged" — the exact response text GitHub's own structured docs data returns in its 200 example. Explicit fact.

Terminology and tone/style are deliberately omitted from this Communication MLE: GitHub's fetched material documents this one exact response string, not a broader terminology or tone convention behind it. GitHub also documents that a blocked merge attempt produces "an error message" for the collaborator — its existence is sourced, but its exact wording is not, so no corresponding Communication MLE is written for that case.

Provenance

Extracted from GitHub's own public REST API and webhook documentation, fetched 2026-08-26, then independently blind-audited for framework conformance and factual accuracy against GitHub's live docs. The audit's one real finding — the merge queue's own documentation page had 404'd during extraction and was left unresolved, when in fact it confirms the queue performs the merge itself — has been fixed above. See the provenance table and decision log for full detail, including why "open" and "merge" are two CRDs, not one.