Quick answer: the three questions
If you use GitHub issues to track work, you have probably noticed the “Create a branch” button in an issue’s sidebar.
It is tempting to click it for every issue, but linking a branch to an issue is a small commitment with real effects on how your work shows up to collaborators.
This guide explains what actually happens when you create a branch for an issue, when the connection helps, and when it is better to wait.
The whole decision comes down to three questions, asked in order:
- Am I starting work on this issue right now?
- Is someone else starting work whose branch I can link manually?
- Is this issue still an undecided discussion?
If you answered yes to the first, create the branch from the issue page.
If the second, link the existing branch from the issue sidebar.
If the third, wait until someone commits to a fix.
The rest of this guide explains why.
What creating a branch for an issue actually does
GitHub lets anyone with write permission to a repository create a branch directly from an issue page.
You click the issue, find the “Development” section in the right sidebar, and choose “Create a branch”.
You can optionally name the branch, choose a destination repository, and decide whether to work locally or open the branch in GitHub Desktop.
By default, the new branch is created in the current repository and from the default branch.
The important part is the connection, not the branch itself.
Branches connected to an issue appear under the “Development” section in the issue’s sidebar.
That section is a visible signal to anyone reading the issue: someone has started working on this.
You can also link multiple branches to a single issue, which is useful when several people approach the same problem from different angles.
One detail worth knowing before you rely on this feature: GitHub documents that the ability to create a branch for an issue is currently in public preview and subject to change.
If your team builds a workflow around it, expect the interface or behavior to evolve.
How the connection changes when you open a pull request
Here is the behavior that surprises people.
When you create a pull request for a branch that is connected to an issue, the pull request is automatically linked to the issue.
At that moment, the branch connection is removed and only the pull request is shown in the “Development” section.
The issue does not end up listing both the branch and the pull request; the pull request takes over as the visible marker of work in progress.
This matters for planning.
If you expect the issue to show a trail of every branch ever created for it, it will not.
The sidebar reflects the current state: either a branch in progress or a pull request, not a history of both.
When creating a branch for an issue helps
The connection earns its place in three common situations.
- You are starting work right away. The feature exists so you can get started immediately from the issue page. If you have just triaged an issue and are about to write code, creating the branch from the issue is the fastest way to begin and to signal that work has begun.
- Collaborators need to see status at a glance. A linked branch tells anyone opening the issue that a fix is in progress without a comment saying so. For shared repositories, that visibility reduces duplicate effort and “is anyone on this?” questions.
- You want automatic linking downstream. Because a pull request from a connected branch is automatically linked to the issue, you skip a manual step later. That automatic link also sets up automatic closing, described below.
A practical illustration: a small team triages issues on Monday.
For each issue someone picks up that day, they create a branch from the issue page.
By Tuesday, every in-progress issue shows a branch under “Development”, and every untouched issue shows nothing.
The sidebar becomes the team’s honest status board, with no extra ceremony.
When it is better to wait
Creating a branch is cheap, but a linked branch is a public claim that work is happening.
Wait when that claim is not true yet.
- The issue is still a discussion. Many issues start as questions or problem reports. If nobody has committed to a fix, a linked branch misleads readers into thinking someone is coding. Leave the issue unlinked until a direction is chosen.
- You are exploring several approaches. If you want to prototype privately before committing to a fix, an unlinked local branch keeps the issue clean. You can always create the connected branch later, once an approach settles.
- The fix is not scoped yet. If the fix might span multiple issues or a refactor, it may be clearer to create the branch when the scope is known, so the connection points at work that actually addresses the issue.
There is also a housekeeping consideration.
Every connected branch is a branch in your repository.
If you create branches speculatively for issues that never move forward, you accumulate stale branches that someone eventually has to clean up.
Creating the branch when work starts, not when the issue is filed, keeps that debt low.
How pull requests close linked issues automatically
The main payoff of linking is automatic closure.
When you merge a linked pull request into the default branch, its linked issue is automatically closed.
You do not need to remember to close the issue by hand.
You can get the same effect without creating a branch from the issue, by using a closing keyword in the pull request description or a commit message.
Supported keywords include close, closes, closed, fix, fixes, fixed, resolve, resolves, and resolved, followed by the issue reference.
For an issue in the same repository, the syntax is the keyword plus the issue number, such as “Closes #10”.
For an issue in a different repository, use the owner and repository name in the reference.
Keywords can be written with colons or in uppercase, so “Closes: #10” and “CLOSES #10” both work.
You can reference multiple issues by giving the full syntax for each one.
Two limitations matter.
First, closing keywords are interpreted only when the pull request targets the repository’s default branch.
If the pull request targets any other branch, the keywords are ignored, no links are created, and merging has no effect on the issues.
Second, if you use a closing keyword in a commit message, the issue closes when the commit merges into the default branch.
However, the pull request containing that commit will not be listed as a linked pull request.
If you want the visible link, put the keyword in the pull request description or link manually.
Manual linking and unlinking
You are not limited to the “Create a branch” flow.
Anyone with write permissions can manually link a pull request to an issue from the pull request sidebar, or link a pull request or branch from the issue sidebar.
You can manually link up to ten issues to each pull request.
When linking from the issue sidebar, the issue can live in a different repository than the pull request or branch.
When linking from the pull request sidebar, the issue and pull request must be in the same repository.
Unlinking has one asymmetry to remember.
Only manually linked pull requests can be manually unlinked.
If you linked an issue using a keyword, you remove the link by editing the pull request description to delete the keyword.
Plan for that if you might change which issue a pull request addresses.
A simple decision path
Put it together as three questions, asked in order.
- Am I starting work on this issue now? If yes, create the branch from the issue page. You get the visible signal and the automatic pull request link later.
- Is someone else starting work, and do I have the branch details? If the work is happening but the branch was created outside GitHub, link it manually from the issue sidebar so the status still shows.
- Is this issue still undecided? Then wait. Keep the issue as a discussion, and create or link a branch only when someone commits to a fix.
The underlying principle is honesty of the signal.
The “Development” section is only useful if it means “work is in progress on this issue right now”.
Every speculative branch you add dilutes that meaning for everyone reading the repository.
What this means for small teams and solo founders
If you are a founder or early operator using GitHub for a side project, you might wonder whether any of this matters when you are the only contributor.
It still does, for two reasons.
First, the automatic close-on-merge behavior saves you from a stale issue list, which is one of the most demoralizing artifacts of a neglected project.
Second, if you ever bring on a collaborator, the habit of connecting work to issues gives them an accurate picture of what is active without a handover document.
For teams, the same habit scales.
Agree on a lightweight norm, such as “create the branch from the issue when you pick it up, and put a closing keyword in the pull request description”.
That single norm covers status visibility, automatic linking, and automatic closure, with no tooling beyond what GitHub already provides.
If you are setting expectations for how a new team works together, it pairs well with writing down other collaboration norms early.
One caution: do not treat the linked branch as a substitute for a clear issue description.
The connection shows that work exists; it does not explain what the fix should do.
A branch named after a vague issue still produces a vague pull request.
Does creating a branch for an issue link the pull request automatically?
Yes, indirectly.
The branch itself is linked to the issue, and when you open a pull request for that branch, the pull request is automatically linked to the issue.
The branch connection is then removed, and only the pull request appears in the “Development” section.
Can I link more than one branch to an issue?
Yes.
GitHub documents that you can link multiple branches for an issue, which suits situations where several people work on the same problem in parallel.
Do closing keywords work on any pull request?
No.
The keywords are interpreted only when the pull request targets the repository’s default branch.
Pull requests aimed at other branches ignore them entirely.
What if I linked the wrong issue?
If the link was manual, you can unlink it.
If it came from a keyword, edit the pull request description to remove the keyword, because keyword-based links cannot be unlinked manually.
The bottom line
Create a branch for an issue when work is genuinely starting and you want the issue to show it, and wait when the issue is still a conversation.
Use a closing keyword in the pull request description so the issue closes itself on merge, remembering that keyword-based automation only works against the default branch.
The feature is in public preview, so treat the exact interface as something that may change, but the habit of connecting work to the issue that motivated it will stay valuable.
For the official steps and current behavior, see GitHub’s documentation on creating a branch for an issue and on linking a pull request to an issue.
If you are deciding how to structure the work before branching, a sprawling issue is often better split first.
Agreeing on team norms early can prevent debates about branching habits later.
Take the next step with Ideoreto. Use the ideas in this guide as a starting point for your next project.
Register for Ideoreto to get started.