Issues

GitHub Issues is the built-in task and bug tracking system that comes with every repository. It is the place where work gets defined before it gets done — where bugs are reported, features are requested, questions are asked, and decisions are documented. Issues are deeply integrated with the rest of GitHub: they connect to pull requests, commits, milestones, and project boards, making them the connective tissue of a project's workflow.

What Issues Are Used For

Issues are not just for bugs. They serve as the general-purpose communication layer for a project:

Any piece of work or conversation that needs to be tracked and resolved belongs in an issue.

Creating an Issue

To open a new issue:

1. Go to the Issues tab of a repository.
2. Click New issue.
3. Fill in the title and description.
4. Set any metadata in the right sidebar (labels, assignees, milestone).
5. Click Submit new issue.

Writing a good issue

A well-written issue makes it easy for someone to understand the problem and act on it without needing additional back-and-forth. For bug reports, include:

• What you expected to happen.
• What actually happened.
• Steps to reproduce the problem exactly.
• Your environment — browser, OS, version number.

For feature requests, include the problem you are trying to solve, not just the solution you have in mind. The solution may evolve during discussion.

Many repositories provide issue templates — pre-filled forms that prompt reporters for the right information. When templates are configured, GitHub displays a template chooser instead of the blank issue form.

Issue Metadata

The right sidebar of an issue contains metadata that organises and contextualises it within the project.

Labels

Labels are coloured tags that categorise issues. They are defined per repository and can represent anything useful:

Labels can be applied to both issues and pull requests. To manage labels for a repository, go to Issues → Labels.

Assignees

Assignees are the people responsible for working on or resolving an issue. An issue can have multiple assignees. Assignees are notified when the issue is assigned to them and the issue appears in their personal issue dashboard.

Milestones

A milestone groups issues and pull requests that belong to a specific goal — a release, a sprint, or a project phase. Each milestone has:

• A title and description.
• An optional due date.
• A progress bar showing how many of its linked items are closed vs. open.

Milestones give teams a high-level view of what is complete and what remains before a target is reached.

The Issue Discussion

Once an issue is open, anyone can participate in the discussion by leaving comments. Comments support full GitHub Flavoured Markdown — code blocks, images, tables, task lists, and @mentions.

Referencing issues and pull requests

Issues can cross-reference each other and pull requests using # followed by the issue or PR number:

This is related to #23 and was introduced in #18.

GitHub renders these as clickable links and shows bidirectional references on both items — clicking through to #23 shows that it was referenced from this issue.

Referencing commits

You can reference a specific commit in an issue comment by pasting its full or abbreviated SHA-1 hash:

This started happening after abc1234.

GitHub links directly to the commit.

Closing Issues via Commits and Pull Requests

One of GitHub's most useful integrations is the ability to close an issue automatically when a related commit or pull request is merged. Use any of these keywords followed by the issue number in a commit message or PR description:

When a commit containing one of these keywords lands on the default branch — either directly or through a merged PR — GitHub automatically closes the referenced issue and adds a cross-reference comment to it.

You can link multiple issues:

Fixes #23, closes #47

This automation removes the manual step of closing issues after merging and keeps the issue tracker accurate without extra effort.

Filtering and Searching Issues

In an active repository, the Issues list can grow large. GitHub provides filtering tools at the top of the Issues tab:

For more precise searches, use the search bar with qualifiers:

is:open label:bug assignee:wariz
is:closed milestone:"v1.0 Release"
is:open no:assignee

Locking and Pinning Issues

Locking

When a conversation becomes unproductive or a closed issue keeps attracting off-topic comments, maintainers can lock it:

1. Scroll to the bottom of the issue.
2. Click Lock conversation.

Locked issues still show their full history but only collaborators with write access can add new comments.

Pinning

Maintainers can pin up to three issues to the top of the Issues list so they are immediately visible to everyone who visits:

1. Open the issue.
2. Click the Pin issue option in the right sidebar.

Pinned issues are useful for highlighting known bugs, important announcements, or the project's current priorities.

Closing an Issue Manually

When an issue is resolved without a linked commit or PR doing it automatically:

1. Scroll to the bottom of the issue.
2. Click Close issue (or Close as completed / Close as not planned).

GitHub added two close states to distinguish between issues that were resolved and issues that were deliberately not addressed:

Closed issues remain permanently visible and searchable — nothing is deleted. They can be reopened at any time.

Issue Templates

Issue templates prompt reporters to fill in structured information rather than a blank text box. They dramatically improve the quality of incoming issues in public repositories.

To set up templates:

1. Go to Settings → General → Features.
2. Click Set up templates next to Issues.
3. Choose from GitHub's built-in templates (Bug report, Feature request) or create custom ones.

Templates are stored as Markdown files in .github/ISSUE_TEMPLATE/. A repository can have multiple templates — contributors choose which one to use when opening a new issue.

Summary