Every project has a to-do list: bugs to fix, features to add, questions to answer. On GitHub, each item on that list is an issue. Issues live inside a repository, have a number, a title, a description and a comment thread, and can be labelled, assigned to people and grouped into milestones.
Issues turn scattered emails and chat messages into an organised, searchable record. Anyone can see what's being worked on, who's doing it and why decisions were made, which is just as useful for a solo project as for a big team.
In this lesson you'll write a good bug report, organise issues with labels and milestones, use task lists and mentions, and connect issues to the commits and pull requests that fix them.
Creating an issue
Open the repository's Issues tab and click New issue. Then:
- Write a specific title: "Search box ignores capital letters", not "Search broken".
- In the description, explain what happened, what you expected and how to reproduce it.
- Add screenshots by pasting or dragging them into the text box.
Issues are written in Markdown, the same format as README files, so you can use headings, lists, links and code blocks.
Labels, assignees and milestones
- Labels categorise issues:
bug,enhancement,documentation,good first issue. You can create your own and give them colours. - Assignees show who is responsible for an issue.
- Milestones group issues into a goal or release, such as "Version 1.0", with a progress bar.
Filter the issue list by any of these: for example, is:open label:bug shows only open bugs.
Task lists and mentions
Inside an issue, a Markdown task list creates checkboxes you can tick as work progresses:
- [x] Design the page
- [ ] Write the HTML
- [ ] Add stylesType @username to mention someone and notify them, and #12 to link to issue or pull request 12. GitHub turns both into links automatically.
Closing issues automatically
Write a closing keyword followed by the issue number in a pull request description or a commit message:
Fixes #23
Closes #23
Resolves #23When the pull request is merged, or the commit reaches the default branch, issue 23 closes and shows a link to the change that fixed it. That gives every bug a clear trail from report to fix.
Finding issues with search qualifiers
The search box above the issue list accepts qualifiers: short key:value filters you can combine. These are the ones you'll use most:
| Qualifier | Finds |
|---|---|
is:open or is:closed | Open or closed issues |
author:@me | Issues you opened |
assignee:@me | Issues assigned to you |
no:assignee | Issues nobody has picked up yet |
label:bug | Issues with that label; quote names with spaces, as in label:"good first issue" |
milestone:"Version 1.0" | Issues in that milestone |
mentions:samlee | Issues that mention a user |
Plain words next to the qualifiers search titles and descriptions too, so is:open label:bug login finds open bugs that mention "login". Put - in front of a qualifier to exclude it: is:open -label:bug shows open issues that aren't bugs.
The filters you type become part of the page's address, so you can bookmark a search you run often or share it with a teammate.
When you close an issue, GitHub asks for a reason, such as completed when the work is done or not planned for ideas you won't pursue and reports you can't reproduce. A short comment explaining the decision is polite, especially towards the person who took the time to report it.
GitHub Issues Syntax
Issue Markdown and keywords
## Steps to reproduce
1. ...
- [ ] task
- [x] finished task
@teammate can you check this?
Related to #12
Fixes #23GitHub Issues Summary
- An issue is a numbered bug report, task or idea inside a repository.
- Good issues have specific titles, steps to reproduce and expected vs actual results.
- Labels, assignees and milestones organise and filter issues.
- Markdown task lists add checkboxes;
@namementions people and#12links items. Fixes #Nin a PR or commit closes issue N when the fix is merged.
GitHub Issues Examples
Each example shows the code, the output it produces and what each part does.
A useful bug report
Title: Search box ignores capital letters
## What happened
Typing "Soup" in the search box shows no results.
## Expected
It should show the same results as typing "soup".
## Steps to reproduce
1. Open the home page
2. Type "Soup" in the search box
Browser: Firefox 129 on Windows 11Issue #23: Search box ignores capital letters
Label: bug Assignee: samlee Milestone: Version 1.1Line-by-line explanation
- Line 1A title that names the exact problem.
- Lines 3 to 7What happened and what should happen.
- Lines 9 to 11Anyone can follow these steps to see the bug.
- Line 13Small details like the browser often explain the cause.
Fix the bug and close the issue from a commit
git switch -c fix-search-case
git commit -am "Make search case-insensitive" -m "Fixes #23"
git push -u origin fix-search-case[fix-search-case 4d9e1a7] Make search case-insensitive
1 file changed, 1 insertion(+), 1 deletion(-)
* [new branch] fix-search-case -> fix-search-caseLine-by-line explanation
- Line 2A second -m adds a body to the commit message containing the closing keyword.
- Line 3Push and open a pull request. When it's merged into main, issue 23 closes itself.
Working with issues in the terminal
gh issue create --title "Add dark mode" --label enhancement
gh issue list --label bug
gh issue close 23 --comment "Fixed in #25"https://github.com/samlee/portfolio/issues/24
Showing 2 of 2 open issues in samlee/portfolio
#21 Footer overlaps text on phones bug
#19 Broken link on about page bug
✓ Closed issue #23 (Search box ignores capital letters)Line-by-line explanation
- Line 1Create a labelled issue without opening the browser.
- Line 2List only the open bugs.
- Line 3Close an issue with a note pointing to the pull request that fixed it.
Common GitHub Issues Mistakes
A vague issue
Title: doesn't work
Body: the site is broken pls fixTitle: Contact form shows error after clicking Send
Body: steps to reproduce, expected result, actual result, screenshotClosing keyword on the wrong line format
Fixed issue 23Fixes #23GitHub only recognises keywords like Fixes, Closes or Resolves followed by #number.
GitHub Issues in Real Projects
Issues in real projects
Large open-source projects receive hundreds of issues a week and rely on labels such as good first issue to welcome new contributors. Teams often view their issues on a GitHub Projects board with columns like To do, In progress and Done, which updates automatically as pull requests are opened and merged.
GitHub Issues FAQ
What is the difference between an issue and a pull request?
An issue describes something to do: a bug, a feature or a question. A pull request proposes actual code changes and asks for them to be merged. A typical pull request links to the issue it solves, with "Fixes #12" in its description.
How do I close several issues with one pull request?
Use a closing keyword for each issue: Fixes #10, fixes #11. Writing Fixes #10, #11 only closes issue 10, because the keyword applies to the number right after it. Each linked issue closes when the pull request is merged into the default branch.
How do I close an issue in a different repository?
Include the owner and repository name before the number: Fixes samlee/website#7. When the pull request is merged into its default branch, that issue closes, as long as you have access to the other repository.
How do I turn off issues for a repository?
In the repository's Settings, untick Issues in the features list. The Issues tab disappears, and existing issues are hidden rather than deleted, so they come back if you turn the feature on again.
Can I move an issue to another repository?
Yes. Use Transfer issue in the issue's sidebar and choose the destination. You need write access to both repositories, and they must belong to the same user or organization. Comments, assignees and any labels or milestones that exist in the new repository come with it.
GitHub Issues Exercises
Answer each one and check it instantly. If you get stuck, open the hint before the answer.
Complete the line so that merging the pull request closes issue 7.
What makes a good issue title?
What does - [ ] Write tests become in an issue?
Which filter shows open issues labelled as bugs?
Which line in a pull request description closes issue 8 when the PR is merged?
GitHub Issues Quiz
5 questions to check what you learned.
What does typing
@samin an issue do?- Assigns the issue to sam
- Closes the issue
- Mentions sam and sends them a notification
- Creates a label
What are milestones used for?
- Deleting old issues
- Counting commits
- Making issues private
- Grouping issues into a goal or release with a progress bar
What does
#15in an issue comment become?- A link to issue or pull request number 15
- A heading
- A comment that's hidden
- A label
Where can a closing keyword such as
Fixes #23go so the issue closes automatically?- Only in the issue itself
- In a pull request description or a commit message that reaches the default branch
- Only in the README
- In a branch name
What makes a useful bug report?
- Just "it doesn't work"
- A screenshot of the home page only
- Steps to reproduce, what you expected and what actually happened
- The word urgent in capitals