This article explains how to connect an issue and a pull request so the issue closes after the merge. After reading it, you can write Closes #number in the pull request title or description, refresh, and confirm that each page lists the other. The keyword has to be English. A keyword in a comment, or a bare #number, does nothing.
A pull request is a request to merge one branch into another. AngusGit calls it a pull request.
The examples use the online repository xlliu/test-pr-example. Issue #4 is titled "折扣示例没有说明空购物车", and its type is Feature. Pull request #9 merges feature/link-empty-cart into main, and its description contains Closes #4. Both are still open. The pages show the state before the merge.
1. Learn which number is which
AngusGit calls an issue an issue. The sidebar entry and the tab on the repository code page are both Issues.
Issues are numbered per repository, starting at #1 and going up. Pull requests are numbered per repository on their own sequence. The two sequences are separate, so one repository can have issue #1 and pull request #1 at the same time. Every Closes #4 in this article means issue #4, not pull request #4.
2. Create an issue and note the number
If the issue already exists, open it, note the number next to the title, and skip to section 3.
- Open the form
Click Issues in the sidebar, then New Issue at the top right. The page title is Create New Issue.
- Fill it in
Set Repository to xlliu/test-pr-example. Set Type to one of Bug, Feature, Question, or Enhancement. The type cannot be changed after you create the issue. This example uses Feature, and the title is "折扣示例没有说明空购物车". In Description, write what is missing. You can leave Labels and Assignees empty.
- Create
Click Create Issue. The message is Issue created successfully. Open the issue. The # and the number next to the title are its number. This example is #4.
3. Write the keyword on the pull request
After you fix the code and push it to a new branch, open a pull request in the usual way. In Title or Description, write a keyword and the issue number:
docs: 说明空购物车不计算折扣
Closes #4
The description of #9 is those two lines. Put one space between the keyword and the number. These nine keywords all work. Case does not matter, and the effect is the same:
| Root | English forms that work | Example |
|---|---|---|
| close |
close, closes, closed
|
Closes #4 |
| fix |
fix, fixes, fixed
|
Fixes #4 |
| resolve |
resolve, resolves, resolved
|
Resolves #4 |
To close several issues at once, write the keyword in front of every number, for example Fixes #4, fixes #5. If you write Fixes #4, #5, only #4 is closed. #5 here only shows the writing. This repository has no issue #5.
Where you write it changes the result:
| Where you write it | Each page lists the other | Closes automatically after merge |
|---|---|---|
| Pull request title or description | Yes | Yes |
| The commit message of a commit on the pull request | No | Yes |
| A comment under the pull request or the issue | No | No |
Only #4, with no keyword in front |
No | No |
| Chinese such as "关闭 #4" or "修复 #4" | No | No |
A reference that includes a repository name, such as owner/other-repo#4
|
No | No |
The safest place is the pull request description. You can confirm the link on the page before the merge, instead of finding out only at merge time.
4. Before you merge, confirm that both sides are linked
The link is calculated from the title and description when the page opens. Refresh after you save the description, and you can see it.
The pull request page shows a Linked Issues section. It lists #4 and its title, with Will close on merge beside it.
The issue page shows a Linked pull requests section. It lists this pull request, and the status is Open.
If neither side appears, go back to the description and check that the keyword is spelled correctly, that there is a space before #, and that the number is an issue in this repository. Delete the keyword from the description and the link disappears with it. There is no separate unlink action.
5. After the merge, the issue closes on its own
When the pull request meets the merge conditions, click Merge pull request. The confirm dialog adds a line: Merging this PR will automatically close 1 issue(s):, and #4 is listed under it. Click Confirm merge.
This example was not merged, so issue #4 and pull request #9 are both still Open. After a merge, issue #4 looks like this:
- The status becomes Closed, and the close reason is Completed.
- The timeline gains a line "{name} closed this issue". The name is the person who clicked merge. The console text is
{actor} closed this issue. - Under Linked pull requests, that request's status becomes Merged.
Two facts are worth knowing before you merge:
-
A merge into any branch closes the issue. If the pull request targets a non-default branch such as
release, the issue still closes after the merge. If you want the issue to count as fixed only when the code reachesmain, write the keyword only on the pull request that merges intomain. - The person who merges does not need permission to close issues. Being able to merge this pull request is enough to close the issue through it.
6. When it does not close on its own
| What you see | Why | What to do |
|---|---|---|
| The pull request page has no Linked Issues section | The title and description have no keyword the system recognizes. For example you wrote only #4, you wrote the Chinese word "关闭", or the keyword is stuck to # with no space |
Change it to a form such as Closes #4, save, and refresh |
| The keyword is in a commit message, and the page shows no link before the merge | A commit message is checked only at merge time. The link on the page looks only at the title and description | This is normal, and the issue still closes after the merge. To confirm early, write the keyword in the description as well |
| You merged, and the issue is still Open | The keyword was in a comment, it pointed at an issue in another repository, or the code was pushed straight to the branch and never went through a pull request | Automatic close happens only when a pull request is merged, and only when the keyword is in the title, the description, or a commit message. If you need it closed, click Close on the issue page |
| You wrote several numbers and only the first one closed | You wrote Fixes #4, #5, and the second number has no keyword in front |
Write the keyword in front of every number. Close the missed one by hand |
| The issue closed too early | The keyword was on a pull request that merged into a non-default branch | On the issue page, click Reopen. From then on, write the keyword only on the request that merges into main
|
Frequently asked questions
Is there a button that links an issue and a pull request by hand?
No. The link is decided entirely by the keyword in the pull request title and description. Write the keyword to create the link. Delete it to remove the link.
I want to mention an issue on the pull request, and I do not want the merge to close it. How do I write that?
Do not use a keyword. Write ordinary text such as "Related issue: #4". It does not appear in the linked list, and the merge does not close the issue.
The issue closed by mistake. How do I restore it?
Open the issue and click Reopen. The status returns to Open. The old comments and the timeline stay.
If I push straight to main and the commit says Fixes #4, does the issue close?
No. Automatic close happens only when a pull request is merged. A commit from a direct push does not trigger it.
Can I pick a reason when I close an issue by hand?
Yes. On the issue page, click Close. The dialog title is Close Issue, and it says "Please select a reason for closing this issue". Choose Completed ("Issue is completed or resolved") or Not Planned ("Issue is not planned or does not need to be addressed"), then click Confirm Close. The reason for an automatic close is always Completed.
Summary
To connect an issue and a pull request, write one English keyword and a number in the pull request title or description, for example Closes #4. Refresh the page and confirm that Linked Issues on the pull request says Will close on merge. After the merge, the issue closes on its own, the reason is recorded as Completed, and the timeline says who merged. A Chinese keyword, a bare number, a keyword in a comment, or a direct push does not create the link and does not close the issue.
Conclusion: Write
Closes #numberin the pull request title or description (orFixes #number, orResolves #number). Each page lists the link, and after the pull request merges the issue is set to Closed with reason Completed.
Top comments (0)