GitHub Issues & Projects
Quick Summary
Issues are GitHub's built-in bug tracker and task list. Projects turn issues into visual kanban boards or spreadsheets for project management. Together they replace external tools like Jira or Trello for many teams.
GitHub Issues
Creating Issues
- Via GitHub Web
- Via GitHub CLI
- Navigate to repository → Issues tab
- Click New Issue
- Fill in title and description
- Assign labels, assignees, milestone, and project
# Install GitHub CLI
# https://cli.github.com
# Create an issue
gh issue create --title "Fix login timeout" --body "JWT expires too quickly" --label "bug"
# List issues
gh issue list
# View issue details
gh issue view 42
# Close an issue
gh issue close 42
Issue Templates
Create .github/ISSUE_TEMPLATE/bug_report.md:
---
name: Bug Report
about: Report a bug to help us improve
labels: bug
---
## Description
A clear description of the bug.
## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error
## Expected Behavior
What you expected to happen.
## Actual Behavior
What actually happened.
## Environment
- OS: [e.g., Ubuntu 22.04]
- Browser: [e.g., Chrome 120]
- Version: [e.g., v2.1.0]
Issue Labels
| Label | Color | Purpose |
|---|---|---|
bug | 🔴 Red | Something isn't working |
feature | 🟢 Green | New feature request |
docs | 🔵 Blue | Documentation changes |
good first issue | 🟣 Purple | Good for newcomers |
priority:high | 🟠 Orange | Needs immediate attention |
wontfix | ⚪ Gray | Won't be addressed |
Linking Issues to PRs
# In your commit or PR description:
"Fixes #42" # Closes issue 42 when PR merges
"Closes #42" # Same effect
"Resolves #42" # Same effect
"Relates to #42" # Links without closing
GitHub Projects
Project Views
| View | Best For |
|---|---|
| Board (Kanban) | Visual workflow tracking |
| Table (Spreadsheet) | Detailed data management |
| Roadmap (Timeline) | Planning across time |
Setting Up a Board
- Go to your profile or org → Projects tab
- Click New project
- Choose Board layout
- Add columns:
Backlog,In Progress,Review,Done - Add issues by dragging or clicking + Add item
Automation
GitHub Projects support built-in automations:
| Trigger | Action |
|---|---|
| Issue opened | Move to Backlog column |
| PR linked to issue | Move to In Progress |
| PR merged | Move to Done |
| Issue closed | Move to Done |
Best Practices
- Use issue templates — ensure consistent bug reports and feature requests
- Label everything — makes filtering and prioritizing fast
- Link PRs to issues — creates traceable history from problem to solution
- Use milestones — group issues by release version
- Review projects weekly — keep boards current and prioritized
What's Next
- GitHub Actions & CI/CD — Automate testing and deployment
- Pages & Releases — Host documentation and publish releases