GitHub Issues
GitHub Issues are discussion threads attached to a repository — bug reports, feature requests, support questions, internal tasks. They’re the lightweight ticket system that lives next to your code, with deep links to commits, PRs, and other issues. For most small-to-medium projects, Issues replace a dedicated issue tracker entirely.
Anatomy of an issue
Title — short, scannable headline.
Description — markdown body with all the detail.
Labels — coloured tags for type, priority, area.
Assignees — who owns the issue.
Milestone — a release or deadline grouping.
Projects — board-style tracking across repos.
Comments — the discussion thread below the description.
Reactions — emoji on the description and comments.
Linked PRs — PRs that reference this issue with closing keywords.
Creating an issue
Click the Issues tab on a repo, then New issue. If the repo has Issue Templates, you’ll see a chooser; pick the closest match. Otherwise you get a blank markdown box.
Three common issue types
Bug report — what happened, what you expected, steps to reproduce, environment.
Feature request — what you want, why, how you’d use it.
Question / support — for projects without a Discussions board.
A good bug report
Template a maintainer will love
### What happened Uploading a PNG larger than 5 MB causes the page to freeze for 10–15 seconds. ### What I expected The upload to complete in the background with progress feedback. ### Steps to reproduce 1. Go to /profile/edit 2. Click "Change avatar" 3. Select any PNG over 5 MB 4. Observe page freeze ### Environment - Browser: Chrome 124 on macOS 14.4 - App version: 2.3.1 - Account type: Pro ### Screenshots [freeze.png]
Issue states
Open — active, awaiting work or discussion.
Closed: completed — work is done, problem solved.
Closed: not planned — won’t fix, duplicate, out of scope.
The "not planned" state was added so projects could archive declined issues without pretending they were completed. Use it.
Closing via commit or PR
Mention a closing keyword in your commit message or PR description and GitHub will auto-close the issue when the change lands on the default branch.
Closing keywords
close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved Examples: Fixes #142 Closes acme-co/widget#88 Resolves #214, fixes #215
References and mentions
Inside an issue or comment
Related to #88 Duplicates #51 See also acme-co/design-system#22 cc @alice cc @acme-co/frontend-team
Reactions
Hover over a comment or the issue description and click the smiley to react. Reactions are how you upvote feature requests without commenting "+1" 200 times. Most maintainers sort the issue queue by 👍 reactions.
Search syntax
Useful search qualifiers
is:issue is:open # all open issues is:issue is:closed reason:completed # closed and completed only is:issue label:bug label:p0 # both labels is:issue author:alice # filed by alice is:issue assignee:@me # assigned to me is:issue mentions:@me # I’m mentioned is:issue no:assignee # unassigned is:issue updated:<2024-01-01 # not touched this year is:issue in:title "memory leak" # title contains the phrase is:issue -label:duplicate # exclude duplicates is:issue sort:reactions-+1-desc # most-upvoted first
Triaging at scale
Run a regular triage rotation — one person spends ~1 hour/week labelling new issues.
Establish a
needs-triagedefault label; remove it once labelled correctly.Close issues that lack a reproducer with a polite ask for one.
Use saved searches like
is:issue label:needs-triage sort:created-ascto attack the oldest first.Apply milestones to bucket work into upcoming releases.
Pinned issues
Repo admins can pin up to three issues to the top of the Issues tab. Use this for: status / outage notices, the contributing guide, a “start here” onboarding issue, or the current sprint board.
GitHub CLI
Issue operations from the terminal
gh issue list # list open issues gh issue list --label bug --assignee @me gh issue view 142 # read an issue gh issue create --title "..." --body "..." gh issue comment 142 --body "Looking now" gh issue close 142 gh issue reopen 142 gh issue edit 142 --add-label p0 --add-assignee alice
Common errors
Issue stays open after PR merges — the closing keyword was in a comment, not the description, or the PR didn’t merge into the default branch.
"You don’t have permission to add labels" — only collaborators can label; contributors must ask.
Notifications overwhelm — tune subscriptions: Watching → Custom → only issues you’re assigned to.