What Are Linked Issues and Closing Keywords in GitHub?
A deep, no-assumptions walkthrough of the small phrases that let a pull request automatically close the Issue it fixes — how they work, why they matter, and how to use them without surprises.
Imagine a hospital where every completed treatment automatically updates a patient’s chart the moment the paperwork is filed — no nurse needs to remember to walk over and manually mark the case as resolved. That small piece of automation removes an entire category of human error: forgotten follow-ups, charts that say “in progress” long after the patient has gone home. Closing keywords in GitHub do exactly this for software work: they let a pull request declare, right in its own description, “this fixes that specific Issue,” so the moment the fix is actually merged, the Issue closes itself — no one has to remember to do it by hand.
1What Are Linked Issues and Closing Keywords?
Let’s build a precise, plain-English definition before exploring exactly how the mechanism works.
The Simple Definition
A closing keyword is a specific word — such as “fixes,” “closes,” or “resolves” — placed directly in a pull request’s description or commit message, immediately followed by a reference to a specific Issue. When GitHub recognizes this pattern, it creates a visible link between the pull request and the Issue, and automatically closes that Issue the moment the pull request is merged into the repository’s default branch.
Think of a restaurant order ticket with a small note scribbled on it: “this completes table 12’s dessert order.” The moment the kitchen marks that ticket as delivered, the front-of-house system can automatically check off that exact line item on table 12’s bill — no separate step required, because the connection was declared right where the work happened.
Why This Feature Exists
Without this connection, a bug fix and the bug report it addresses can easily drift apart — a developer merges a fix, forgets to go close the original Issue, and it sits open indefinitely, misleading anyone who later checks whether the problem was actually resolved. Closing keywords remove this entirely from human memory, turning “did I remember to close that Issue?” into something GitHub handles automatically and reliably, every single time.
The automatic closing only happens once the pull request is actually merged into the repository’s default branch — simply opening a pull request with a closing keyword in its description does not close the Issue immediately.
2The Common Closing Keywords
GitHub recognizes a small family of related keywords, all functioning identically, purely offered as natural-language synonyms.
close / closes / closed
The most general-purpose keyword, appropriate for any Issue this pull request resolves, regardless of whether it was originally framed as a bug.
fix / fixes / fixed
The most natural phrasing specifically for bug-report Issues, since it reads as a direct statement that this pull request fixes the described problem.
resolve / resolves / resolved
A slightly more formal alternative, often preferred for Issues framed as broader requests or discussions rather than strictly defined bugs.
These keywords don’t behave differently from one another in any functional sense — “fixes,” “closes,” and “resolves” all trigger the exact same automatic-closing behavior. The choice between them is purely about which one reads most naturally for a given Issue.
3How GitHub Recognizes the Pattern
Understanding exactly what GitHub is looking for helps avoid the most common mistake beginners make with this feature.
GitHub scans a pull request’s description (and, separately, individual commit messages) for one of the recognized keywords immediately followed by a reference to an Issue — most commonly written as the pound sign directly followed by that Issue’s number, and referencing an Issue in the same repository the pull request belongs to. The keyword and the Issue reference must appear right next to each other for GitHub to recognize the connection; simply mentioning both somewhere in a long paragraph, without them directly adjacent, won’t trigger the automatic link.
graph LR
T["Text: 'fixes' immediately followed by an Issue reference"] --> R[GitHub recognizes the pattern]
R --> L[Pull request and Issue become linked]
L --> M[Pull request is merged]
M --> C[Linked Issue closes automatically]
A closing keyword can appear in the pull request’s own description, or in an individual commit’s message — both places are scanned, giving developers flexibility in exactly where they declare the connection.
4Referencing Issues in a Different Repository
Closing keywords aren’t limited to Issues living in the exact same repository as the pull request itself.
When a fix in one repository actually resolves a problem tracked in a different, separate repository — common in larger organizations with many interconnected codebases — a closing keyword can reference that other repository’s Issue by including its full identifying path alongside the keyword. GitHub recognizes this fuller reference just as reliably, linking and closing across repository boundaries, not just within a single one.
A Shared Library Fix Resolving a Downstream Bug
If a bug reported in an application’s repository actually traces back to a shared library maintained in a completely separate repository, the pull request fixing the library can still automatically close the original bug report in the application’s repository, once it’s referenced fully and correctly.
5Linking Without Automatically Closing
Sometimes a team wants the visible connection between a pull request and an Issue, without the automatic closing behavior.
Simply mentioning an Issue’s reference without one of the recognized closing keywords in front of it — for example, just writing “related to” followed by the Issue reference — creates a visible cross-reference between the two, showing up in each one’s activity timeline, but does not trigger any automatic closing when the pull request merges. This distinction matters for pull requests that only partially address an Issue, or that are related to it without fully resolving it.
| Phrasing Style | Creates a Visible Link? | Automatically Closes the Issue? |
|---|---|---|
| “Fixes #123” | Yes | Yes, once merged |
| “Related to #123” | Yes | No |
| Just “#123” with no keyword | Yes | No |
Simply typing an Issue’s reference number anywhere in a pull request’s description does create a visible link between the two, but it will not automatically close that Issue unless a recognized closing keyword sits directly in front of it.
6Linking Multiple Issues to One Pull Request
A single pull request isn’t limited to closing just one Issue — sometimes a change genuinely resolves several at once.
Multiple closing keywords can appear together
A pull request’s description can include several separate closing-keyword-plus-reference pairs, one for each distinct Issue the change resolves.
Each is recognized and linked independently
GitHub scans and links every recognized pair separately, so the pull request shows up connected to each of the Issues it references.
All linked Issues close together on merge
The moment the pull request is merged, every Issue that was linked with a genuine closing keyword closes automatically, all at once.
This is especially useful when a single, larger fix happens to resolve several separately reported but closely related bugs — rather than closing each one manually after the fact, they can all be declared and closed together in one pull request.
7What Happens If the Pull Request Is Closed Without Merging
The automatic-closing behavior is specifically tied to merging, not simply to closing a pull request in any way.
If a pull request with a closing keyword is closed without ever being merged — perhaps the approach was abandoned, or a different solution was chosen instead — the linked Issue does not automatically close. The link itself remains visible in the Issue’s activity history for reference, but the automatic closing behavior only ever fires as a direct consequence of an actual merge into the default branch.
graph TD
PR[Pull request with a closing keyword] --> Q{How does it end?}
Q -- Merged --> C[Linked Issue closes automatically]
Q -- Closed without merging --> N[Issue remains open; link still visible]
8Why Traceability Matters
Beyond the simple convenience of automatic closing, this feature builds something genuinely valuable over a project’s lifetime.
Every linked Issue and pull request pair becomes a small, permanent, two-way pointer in the project’s history: from the Issue, you can always see exactly which code change resolved it; from the pull request, you can always see exactly which reported problem it was addressing. Over months and years, this accumulated web of connections turns a repository’s history into a genuinely navigable, self-documenting record — incredibly valuable when investigating an old bug, understanding why a particular piece of code exists, or onboarding someone new to a mature project.
9Advantages and Trade-offs
This small, lightweight feature brings genuine, compounding benefits, with only a few minor things to watch out for.
Advantages
- Removes the need to remember to manually close an Issue after merging its fix.
- Creates a permanent, two-way traceable link between problems and their solutions.
- Works seamlessly across repositories, not just within a single one.
- Supports closing several related Issues from a single pull request at once.
- Requires no special tooling — just a specific, easy-to-learn phrasing pattern in plain text.
Disadvantages / Trade-offs
- Easy to trigger accidentally if a keyword and Issue reference happen to sit adjacent unintentionally.
- Only fires on an actual merge, which can surprise someone expecting closure on a different kind of pull request resolution.
- Requires the keyword and reference to be directly adjacent, which isn’t always obvious to newcomers.
- Doesn’t distinguish between a full fix and a partial one — both trigger the same full closure.
10Design Patterns and Anti-Patterns
Real-world usage of closing keywords has surfaced some clear patterns worth adopting, and some worth avoiding.
Pattern: One Line, Clearly Placed
Many teams place their closing keyword on its own dedicated line at the top of the pull request description, making it instantly visible to reviewers and unambiguous to GitHub’s own recognition.
Problem
A developer writes “this partially resolves the login timeout described in #245, though more work is needed” as part of a longer paragraph in a pull request description.
Why It’s Harmful
Because the word “resolves” sits directly adjacent to the Issue reference, GitHub recognizes it as a genuine closing keyword and will close Issue #245 entirely upon merge, even though the developer’s own sentence explicitly says the fix is only partial.
Correct Approach
Use a non-closing phrase like “related to #245” for a partial fix, and reserve a genuine closing keyword only for pull requests that the author is confident fully resolve the linked Issue.
Problem
A team never uses closing keywords at all, always closing Issues manually well after merging their corresponding pull requests.
Why It’s Harmful
Issues frequently sit open for days after their actual fix has shipped, since closing them relies entirely on someone remembering to circle back — and the valuable, permanent, two-way trace between problem and solution never gets recorded at all.
Correct Approach
Build the habit of including an appropriate closing keyword directly in the pull request description as a normal part of writing it, so the connection and the closure both happen automatically and reliably.
11Best Practices and Common Mistakes
A practical checklist for using closing keywords well, day to day.
Only close Issues your pull request genuinely, fully resolves
Reserve closing keywords for changes that truly finish the job — use a non-closing reference for anything partial or related instead.
Place the keyword somewhere clear and easy to spot
Putting it near the top of the pull request description, on its own line, makes the connection obvious to both reviewers and future readers.
Assuming a closing keyword works on an unrelated draft
Double-check that a closing keyword is only present when the pull request is genuinely ready and intended to resolve that Issue, not left over from an earlier, different draft.
Relying on closing keywords for cross-referencing without closure
If the goal is purely to show a relationship without triggering automatic closure, use a phrase like “related to” instead of a genuine closing keyword.
12Real-World and Industry Examples
Closing keywords are a small feature with genuinely widespread, everyday impact across countless teams.
Open-Source Bug Triage
Maintainers of popular open-source projects rely heavily on closing keywords to keep their Issue tracker accurate without constant manual bookkeeping, given the sheer volume of incoming reports and fixes.
Automated Changelogs
Some teams build automated release notes by scanning exactly which Issues were closed by merged pull requests between two versions, relying directly on this linking mechanism to generate an accurate summary.
Compliance and Audit Trails
Organizations with formal change-tracking requirements benefit from the permanent, automatic record closing keywords create, linking exactly which code change resolved exactly which reported issue.
13Frequently Asked Questions
Yes — “closes,” “fixes,” and “resolves,” along with their other grammatical forms, all trigger the exact same automatic-closing behavior. The choice between them is purely a matter of natural phrasing.
No — the Issue only closes once the pull request is actually merged into the repository’s default branch, not simply when it’s opened or approved.
Yes — simply referencing the Issue’s number without a recognized closing keyword directly in front of it creates a visible link without any automatic closing.
Yes — by including the other repository’s full path alongside the Issue reference, a closing keyword can link and close an Issue that lives in a separate repository entirely.
Any linked Issue remains open. The automatic-closing behavior only fires as a direct result of an actual merge, not simply from the pull request being closed in any other way.
Yes — a pull request description can include multiple separate closing-keyword-plus-reference pairs, and every one of them will close automatically once the pull request is merged.
14Summary and Key Takeaways
Closing keywords are a small, plain-text phrase — like “fixes,” “closes,” or “resolves,” followed directly by an Issue reference — that let a pull request declare exactly which Issue it addresses, automatically closing that Issue the moment the pull request is actually merged. Beyond the simple convenience of never having to remember a manual closing step, this small habit builds a permanent, two-way traceable link between every reported problem and the exact code change that resolved it, turning a project’s history into a genuinely navigable, self-documenting record over time. Used thoughtfully — reserved only for changes that truly, fully resolve an Issue — it’s one of the highest-value, lowest-effort habits a team can build into its everyday workflow.
Key Takeaways
- A keyword plus an adjacent reference — the specific word must sit directly next to the Issue number to be recognized.
- Closes only on merge — opening or closing a pull request without merging never triggers the automatic closure.
- Several equivalent keywords — “fixes,” “closes,” and “resolves” all behave identically; the choice is purely phrasing.
- Works across repositories — a fix in one repository can automatically close an Issue tracked in another.
- Multiple Issues, one pull request — several closing-keyword pairs can all be declared and closed together at once.
- Reserve it for true fixes — use a non-closing reference like “related to” for anything only partially addressed.
- Builds lasting traceability — every link becomes a permanent record connecting a problem to exactly how it was solved.