GitHub Issues
GitHub Issues is a built-in tool for tracking bugs, requesting features, assigning tasks, and discussing project updates directly within a GitHub repository.
Developers, project managers, and contributors can use issues to organize work, assign responsibilities, and track progress throughout the software development process.
1. Core Features of a GitHub Issue
Each issue provides several tools to help teams manage their work.
| Feature | Purpose | Example |
|---|---|---|
| Title and Description | Describe the problem or task. Markdown supports headings, lists, code, and checklists. | Fix login validation |
| Assignees | Identify the team members responsible for resolving an issue. | Assign to a backend developer |
| Labels | Categorize issues so they can be filtered and prioritized. | bug, enhancement |
| Milestones | Group issues around a release or project goal. | v1.0.0 Release |
bug label, assign a developer, and track
the fix until completion.
2. Creating an Issue
- Open your repository on GitHub.
- Select the Issues tab.
- Click New issue.
- Enter a clear title and detailed description.
- Add labels, assignees, or a milestone if needed.
- Click Create to submit the issue.
A good issue description explains the problem, steps to reproduce it, expected behavior, actual behavior, and any relevant error messages.
3. Connecting Issues to Branches
GitHub can connect issues to development branches and pull requests. When available, use the issue's Create a branch option to create a branch associated with the task.
For example, a branch for issue number 12 might be named:
12-fix-login-bug
Developers can make changes on this branch and then open a pull request to review and merge those changes.
4. Automatically Closing Issues
GitHub recognizes special keywords in commit messages and pull request descriptions. When the associated change is merged into the repository's default branch, these keywords can automatically close the issue.
Example commit message:
Fixes #12 - Correct the login button styling
Common closing keywords include:
close,closes,closedfix,fixes,fixedresolve,resolves,resolved
5. Using Issue Templates
Issue templates help contributors submit consistent, useful bug reports and feature requests instead of vague descriptions.
Create templates inside the following repository folder:
.github/ISSUE_TEMPLATE/
For example, a bug report template can ask for:
- Bug summary
- Steps to reproduce the problem
- Expected behavior
- Actual behavior
- Operating system and browser details
- Error messages or logs
GitHub supports Markdown issue templates and YAML-based issue forms, which can collect structured information from contributors.
6. GitHub Issues vs. GitHub Projects
| GitHub Issues | GitHub Projects |
|---|---|
| Tracks individual bugs, tasks, and feature requests. | Organizes and tracks work across multiple issues and pull requests. |
| Provides descriptions, labels, assignees, and discussions. | Provides views such as tables, boards, and roadmaps. |
| Best for recording and managing individual work items. | Best for visualizing progress across a project. |
7. Best Practices
- Use clear and descriptive issue titles.
- Include steps to reproduce bugs.
- Use labels consistently across the team.
- Assign an owner when responsibility is clear.
- Link related branches and pull requests.
- Close completed issues and keep project status updated.