Why is this a Capability MLE? Proposing changes for review has an independent, determinable outcome (an open, addressable pull request, or a rejection) that is complete on its own — before anyone reviews, merges, or closes it.
What does this example teach? How to extract a CRD from public evidence with audited provenance, and how one real capability can have several existing realizations at once (web UI, REST, GraphQL, CLI, and bot automation) without becoming several capabilities.
Evidence status: extracted from GitHub's own public documentation, independently blind-audited for conformance and factual accuracy.
Identity and core meaning
Interaction Contract MLE
Create a pull request
- Actor
- A repository collaborator (or organization member) with write access to the head/source branch, which may be a branch in a fork the actor owns.
- Command / intent
- Propose that the commits on a named branch be integrated into a named target branch, supplying a title/body or converting an existing issue.
- Policies / invariants
- Write access to the head/source branch required; two distinct branches required; title required unless issue is supplied; draft availability is plan-gated.
- Transition
- No pull request for this proposal → an open pull request, in "ready for review" or "draft" state.
- Result
- 201 with the created resource, or 403/422 with an identifiable reason.
- Events / effects
pull_requestwebhook event,action: opened; notifications to other users/systems.- Unknowns
- Whether a duplicate open PR for the same head→base pair is blocked; the general non-human-actor authorization boundary beyond the confirmed Dependabot case.
Rules and defaults
Rules / invariants
- Write access to the head/source branch (or org membership) is required to open or update a pull request.
- A pull request requires two distinct branches; it cannot be opened against itself.
- Draft pull requests are gated by the repository's/organization's GitHub plan.
Recommended defaults
- The raw markdown response media type is GitHub's own stated default if none is specified.
- A pull request is likely "ready for review" unless
draftis explicitly set true — a reasonable inference, not a confirmed default.
Optional: operational realization
software-primary for the REST/GraphQL/CLI/web-UI paths; unknown for Dependabot's internal decision process.| Known realization | Confirmed via |
|---|---|
| github.com web UI | "Compare & pull request" flow; base vs. compare branch selection; standard or draft creation button. |
| GitHub REST API | POST /repos/{owner}/{repo}/pulls — full parameter/response/status-code set confirmed from GitHub's own structured docs data. |
| GitHub GraphQL API | Existence confirmed via cross-reference only; specific mutation not independently retrievable. |
| GitHub CLI | gh pr create [flags] — base/head/title/body/draft flags confirmed. |
| Dependabot (bot/automation) | GitHub's own docs: "When Dependabot identifies an outdated dependency, it raises a pull request..." — confirmed to open PRs, not confirmed to merge them. |
Unknown / unresolved
- Whether a second open pull request for the same head→base pair is blocked.
- The exact per-action webhook description text for
opened. - The general non-human-actor authorization boundary beyond the confirmed Dependabot case.
- Any request-volume limit beyond the general secondary-rate-limit warning.
See the full unresolved questions document for the complete list shared with Merge a pull request.
Related MLEs by Dimension
Traceability only, evidence-bound like the rest of this extraction — a dimension is included only where GitHub's own fetched material states something to trace to. Five dimensions are omitted here, each for a stated reason: Interaction/Behaviour (self-referential to this capability's own sole contract, above), Communication (GitHub confirms this action triggers notifications but never documents their wording — unlike Merge a pull request, which has an exact quoted response string to ground a Communication MLE on), Backend/Execution and Data/Information (GitHub documents its public API contract, not its internal implementation or data model), and Verification (this CRD's own operational realization already states tests aren't documented by GitHub as part of this material).
| Dimension | Relationship | Ref | Notes |
|---|---|---|---|
| Business/Domain | constrains | Write-access/org-membership requirement; draft-PR plan-gating | Already stated under Rules; referenced here. |
| UX/Experience | supports | Base vs. compare branch selection concept; "Compare & pull request" banner | |
| Frontend/Interface | supports | Separate "Create pull request" vs. "Create draft pull request" buttons | |
| API/Interoperability | implements | POST /repos/{owner}/{repo}/pulls; GraphQL (existence only); gh pr create | Already stated under known realizations. |
| Agentic | supports | Dependabot | Already stated above. |
| Operations | supports | Secondary rate-limiting risk on rapid creation; draft-PR plan availability |
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 — one real defect (a merge-queue realization on the paired Merge a pull request CRD) and three small provenance/tag cleanups were found and fixed. See the provenance table and decision log for full detail, including why "open" and "merge" are two CRDs, not one.