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.