GitHub Issues and Project Boards
GitHub Issues is a lightweight tracker built directly into every repository. It exists so that discussion about bugs, feature requests, and tasks lives next to the code it concerns, rather than in a separate ticketing system disconnected from commits and pull requests. Each issue is a single unit of work with a title, a Markdown body, labels, assignees, and a comment thread. Because issues can be referenced from commit messages and pull requests using '#123' syntax, and because pull requests can automatically close issues with keywords like 'Closes #123', GitHub Issues creates a traceable link between 'why we changed something' and 'what actually changed'. Project boards then take a collection of issues and pull requests and arrange them spatially — typically as columns like Backlog, In Progress, In Review, and Done — so a team can see the shape of its work at a glance without reading every issue individually.
Cricket analogy: Instead of complaints about a bowler's no-ball technique living in a separate notebook, GitHub Issues keeps that discussion pinned right next to the match footage, and closing the issue with 'Closes #123' links the fix directly to the corrected delivery, all visible on one board with columns like Nets, Playing XI, and Post-Match Review.
Anatomy of a good issue
A well-written issue answers three questions: what is the current behavior, what is the expected behavior, and how can someone reproduce the gap between them. Bug reports benefit from reproduction steps, environment details, and screenshots or logs. Feature requests benefit from a clear problem statement before jumping to a proposed solution, since the same underlying need can sometimes be met more simply than the reporter imagined. Labels such as 'bug', 'enhancement', 'good first issue', and 'wontfix' let maintainers triage at scale, while milestones group issues that must ship together for a release. Assignees signal ownership, but on healthy teams an issue being unassigned does not mean it is unimportant — it usually just means it has not yet been picked up.
Cricket analogy: A well-written injury report for a fast bowler states current fitness, expected match-readiness, and how the strain occurred, complete with scan images; labels like 'niggle', 'stress-fracture', and 'good-to-go' let the physio team triage the whole squad at a glance.
Projects (the board itself)
GitHub Projects is a flexible, spreadsheet-and-board hybrid that sits above issues and pull requests. Unlike a plain issue list, a Project can pull items from multiple repositories into one view, add custom fields (priority, estimate, sprint, target date), and offer multiple layouts — a Kanban-style board, a table, or a roadmap timeline — over the same underlying data. Automation rules can move a card to 'In Progress' when someone opens a linked pull request, and to 'Done' when that pull request merges, so the board reflects reality without manual bookkeeping. This matters for larger teams: a board that requires constant manual updates quickly goes stale and stops being trusted.
Cricket analogy: A season-wide selection dashboard pulls form data from every domestic team into one view, adds custom fields like fitness score and role, and automatically moves a player from 'Watchlist' to 'Squad' when they're picked, so selectors never rely on stale spreadsheets.
# Reference an issue from a commit message so it shows up on the issue timeline
git commit -m "fix: correct off-by-one error in pagination (refs #482)"
# Using the GitHub CLI to create and manage issues without leaving the terminal
gh issue create --title "Login form rejects valid emails with plus signs" \
--body "Steps to reproduce:\n1. Enter user+test@example.com\n2. Submit\nExpected: accepted. Actual: 'invalid email' error." \
--label bug --assignee octocat
gh issue list --label bug --state open
# A pull request description that will auto-close the issue on merge
# (place this line in the PR body, not the commit message)
# Closes #482The 'Closes #123' keyword only auto-closes an issue when the pull request merges into the repository's default branch. If your team merges feature branches into a long-lived integration branch first, the issue will stay open until that branch is eventually merged to main — a common source of confusion during release freezes.
Deleting an issue is permanent and, unlike closing it, removes it from search and from any Project board it appeared on. In almost all cases you want to close an issue (with a reason: 'completed' or 'not planned') rather than delete it, so the history and discussion remain searchable.
Triage and prioritization workflows
Mature teams run a regular triage ritual: new issues land in a 'Needs triage' column or label, and during triage someone assigns severity, labels, and a rough size estimate. Custom fields on a Project board (like a single-select 'Priority: P0/P1/P2' field) let the board be filtered and sorted without changing the underlying issue text. Views can be saved per audience — engineers might filter to 'my open items sorted by priority', while a manager might view a roadmap grouped by milestone. The goal of all this structure is the same: make it fast to answer 'what should I work on next' and 'are we on track for the release' without a status-update meeting.
Cricket analogy: Every Monday the selection committee reviews a 'Needs Assessment' pool of uncapped players, assigning tier, role, and readiness labels; a priority field lets selectors filter to 'must-watch this series' while the coach views by tournament without needing a status meeting.
- Issues are per-repository units of work with titles, labels, assignees, and comment threads.
- Closing keywords ('Closes #123', 'Fixes #123') in a PR description auto-close the linked issue on merge to the default branch.
- GitHub Projects can aggregate issues and PRs across multiple repositories into one board, table, or roadmap view.
- Custom fields (priority, estimate, sprint) let a Project board carry planning metadata the issue text does not.
- Automation rules can move cards between columns automatically based on PR and issue state changes.
- Prefer closing issues over deleting them to preserve searchable history and discussion.
Practice what you learned
1. Which pull request description keyword will automatically close a linked issue when the PR merges into the default branch?
2. What is a key advantage of a GitHub Project board over a single repository's issue list?
3. What happens if you delete an issue instead of closing it?
4. In a triage workflow, what is the primary purpose of a custom single-select field like 'Priority' on a Project board?
5. Referencing '#482' inside a commit message primarily achieves what?
Was this page helpful?
You May Also Like
Pull Requests and Code Review
How pull requests turn a branch into a reviewable, discussable proposal for merging code, and the practices that make code review effective rather than a rubber stamp.
Branch Protection and CI Checks
Explore how branch protection rules and required CI status checks stop broken or unreviewed code from reaching important branches like main.
Commit Message Conventions
Why disciplined, structured commit messages make history searchable and automatable, and how conventions like Conventional Commits standardize their format.
Feature Branch Workflow
A widely used team workflow where every change lives on its own short-lived branch off main, gets reviewed via pull request, and is merged once approved and tested.
Related Reading
Related Study Notes in Software Engineering
Browse all study notesMicroservices Study Notes
Software Architecture · 30 topics
Software EngineeringTesting & TDD Study Notes
Software Testing · 30 topics
Software EngineeringDesign Patterns Study Notes
Software Design · 30 topics
Software EngineeringSoftware Engineering Study Notes
Python · 40 topics
Software EngineeringSystem Design Study Notes
Architecture · 40 topics