Git & GitHub
GitHub Issues
GitHub Issues
GitHub Issues is a powerful tracking system built into every repository. It's perfect for tracking bugs, planning features, managing tasks, and facilitating discussions. Issues are one of the most important collaboration tools on GitHub and are used by teams of all sizes, from individual developers to large open-source projects.
What are GitHub Issues?
Issues are tickets that track ideas, enhancements, tasks, or bugs for your project:
Issues can be used for:
✓ Bug reports and tracking
✓ Feature requests and planning
✓ Task management and to-do lists
✓ Documentation improvements
✓ Questions and discussions
✓ Release planning and milestones
✓ Project roadmap tracking
Key Features:
- Markdown support for rich formatting
- Labels for categorization
- Assignees for responsibility
- Milestones for grouping
- Comments for discussion
- Cross-referencing with commits/PRs
- Search and filtering
- Email notifications
Pro Tip: Issues are public in public repositories and visible to everyone. Use issues transparently to build community trust and encourage contributions.
Creating an Issue
Creating issues is straightforward:
Via GitHub Web Interface:
1. Go to your repository
2. Click "Issues" tab
3. Click "New issue" button
4. Enter a descriptive title
5. Write detailed description
6. Add labels (optional)
7. Assign to someone (optional)
8. Link to milestone (optional)
9. Click "Submit new issue"
Via GitHub CLI:
# Create simple issue
gh issue create --title "Bug: Login fails" --body "Description here"
# Interactive issue creation
gh issue create
# Create with labels and assignees
gh issue create --title "Feature request" \
--body "Details..." \
--label "enhancement" \
--assignee username
Writing Effective Issue Descriptions
A well-written issue saves time and gets faster responses:
Bug Report Template:
**Description**
A clear description of the bug
**Steps to Reproduce**
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error
**Expected Behavior**
What should happen
**Actual Behavior**
What actually happens
**Screenshots**
If applicable, add screenshots
**Environment**
- OS: macOS 13.0
- Browser: Chrome 118
- Version: 2.1.0
**Additional Context**
Any other relevant information
Feature Request Template:
**Problem Statement**
Describe the problem this feature would solve
**Proposed Solution**
Describe your proposed solution
**Alternative Solutions**
Describe alternatives you've considered
**Benefits**
Who would benefit and how?
**Implementation Notes**
Technical considerations (optional)
**Examples**
Links to similar implementations
Best Practice: Use clear, descriptive titles. "Login button doesn't work on mobile" is better than "Bug" or "Please fix this".
Issue Templates
Issue templates standardize how contributors report issues:
Creating Issue Templates:
1. Create .github/ISSUE_TEMPLATE/ directory
2. Add template files:
- bug_report.md
- feature_request.md
- custom_template.md
Example bug_report.md:
---
name: Bug Report
about: Report a bug to help us improve
title: '[BUG] '
labels: bug
assignees: ''
---
## Bug Description
A clear description of what the bug is.
## Steps to Reproduce
1. Step one
2. Step two
3. See error
## Expected Behavior
What you expected to happen.
## Screenshots
If applicable, add screenshots.
## Environment
- OS: [e.g. macOS]
- Version: [e.g. 1.0.0]
Alternative: YAML templates (recommended):
Create: .github/ISSUE_TEMPLATE/bug_report.yml
name: Bug Report
description: File a bug report
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Thanks for reporting a bug!
- type: textarea
id: description
attributes:
label: Bug Description
description: A clear description of the bug
placeholder: Tell us what went wrong
validations:
required: true
- type: dropdown
id: severity
attributes:
label: Severity
options:
- Critical
- Major
- Minor
validations:
required: true
Labels: Organizing Issues
Labels categorize and filter issues effectively:
Default GitHub Labels:
bug - Something isn't working
documentation - Documentation improvements
duplicate - This issue already exists
enhancement - New feature or request
good first issue - Good for newcomers
help wanted - Extra attention needed
invalid - This doesn't seem right
question - Further information requested
wontfix - This will not be worked on
Custom Labels Examples:
Priority labels:
- priority: high (red)
- priority: medium (orange)
- priority: low (yellow)
Status labels:
- status: needs-review (purple)
- status: in-progress (blue)
- status: blocked (red)
Type labels:
- type: frontend (green)
- type: backend (blue)
- type: database (purple)
Managing Labels:
# Via Web Interface:
Issues → Labels → New label or Edit
# Via GitHub CLI:
gh label create "priority: high" --color FF0000
gh label list
gh label delete "old-label"
# Add label to issue:
gh issue edit 123 --add-label "bug,priority: high"
Color Coding: Use consistent colors: red for urgent/bugs, green for enhancements, blue for tasks, yellow for questions. This helps with quick visual scanning.
Milestones: Grouping Issues
Milestones group related issues toward a common goal:
Common Milestone Uses:
- Version releases (v1.0, v2.0, v2.1)
- Sprint cycles (Sprint 1, Sprint 2)
- Project phases (Alpha, Beta, Launch)
- Time-based goals (Q1 2024, December Release)
Creating Milestones:
Via Web: Issues → Milestones → New milestone
- Title: v2.0 Release
- Due date: 2024-12-31
- Description: Features and bugs for version 2.0
Via CLI:
gh api repos/:owner/:repo/milestones \
-f title="v2.0 Release" \
-f due_on="2024-12-31T23:59:59Z"
Milestones show progress visually with completion percentage based on closed vs open issues.
Assignees: Delegating Responsibility
Assign issues to team members to clarify ownership:
Assigning Issues:
# Single assignee
Click issue → Assignees → Select person
# Multiple assignees (Teams/Pro)
You can assign up to 10 people per issue
# Via CLI:
gh issue edit 123 --assignee username1,username2
# Assign to yourself:
gh issue edit 123 --assignee @me
# Remove assignee:
gh issue edit 123 --remove-assignee username
Note: Only repository collaborators can be assigned to issues. External contributors cannot be assigned, but they can comment and contribute.
Linking Issues to Commits and Pull Requests
Connect issues to the code that resolves them:
Reference Issues in Commits:
# Just mention the issue (doesn't close it)
git commit -m "Update login validation, see #123"
# Reference multiple issues
git commit -m "Fix bugs #123 #456 #789"
# Link to issue in another repo
git commit -m "Fix user/repo#123"
Auto-Close Issues with Keywords:
# These keywords close the issue when PR merges:
close #123
closes #123
closed #123
fix #123
fixes #123
fixed #123
resolve #123
resolves #123
resolved #123
# Example commit:
git commit -m "Fix login validation
This commit resolves the authentication bug
reported by multiple users.
Fixes #123"
Reference in Pull Requests:
When creating PR, mention issues in description:
This PR addresses #123 and partially fixes #456.
## Changes
- Updated authentication logic
- Added input validation
- Improved error messages
Closes #123
Related to #456
Link Issues to PRs:
In issue sidebar → Development → Link PR
Pro Tip: Use "Closes #123" in PR description (not commit message) for better tracking. The issue will close automatically when PR is merged.
Issue References and Mentions
GitHub creates automatic links when you reference issues:
Reference Syntax:
#123 - Issue in same repository
user/repo#123 - Issue in another repository
@username - Mention a user (they get notified)
Where references work:
- Issue descriptions
- Comments
- Commit messages
- Pull request descriptions
- Code review comments
- Discussion threads
Example Comment:
I think this is related to #45 and #67.
@john can you review this?
Also see user/other-repo#123 for context.
Searching and Filtering Issues
GitHub provides powerful search capabilities:
Basic Filters:
# Built-in filters (click in Issues tab):
- Open issues
- Your issues (assigned to you)
- Issues you created
- Issues mentioning you
Search Syntax:
is:issue is:open - Open issues
is:issue is:closed - Closed issues
label:bug - Issues with bug label
assignee:username - Assigned to user
author:username - Created by user
mentions:username - Mentioning user
milestone:"v2.0" - In milestone
no:label - Without any labels
no:assignee - Unassigned issues
created:>2024-01-01 - Created after date
updated:<2024-01-01 - Updated before date
Combine Filters:
is:open label:bug assignee:@me
is:issue label:enhancement milestone:"v2.0"
is:open no:assignee label:"good first issue"
CLI Search:
# List all open issues
gh issue list
# Filter by label
gh issue list --label bug
# Filter by assignee
gh issue list --assignee @me
# Filter by state
gh issue list --state closed
# Search by text
gh issue list --search "login bug"
# Limit results
gh issue list --limit 20
Projects: Organizing Issues
GitHub Projects provide Kanban-style boards for issues:
Creating Projects:
1. Go to repository Projects tab
2. Click "New project"
3. Choose template:
- Board view (Kanban)
- Table view (Spreadsheet)
- Roadmap view (Timeline)
4. Add issues to project
5. Organize in columns (To Do, In Progress, Done)
Project Automation:
- Auto-add new issues
- Auto-move on status change
- Auto-close when PR merges
- Custom workflows
Managing Issue Notifications
Control how you receive issue updates:
Notification Levels:
Watch - All activity notifications
Participating - Only @mentions and assigned
Ignore - No notifications
Customize Notifications:
Settings → Notifications → Customize
- Email notifications
- Web notifications
- Mobile push (GitHub Mobile app)
- Scheduled digest (daily/weekly)
Unsubscribe from Issue:
Click "Unsubscribe" in issue sidebar
Hands-On Exercise:
Practice with GitHub Issues:
- Create 5 different issues in your test repository:
- 1 bug report
- 1 feature request
- 3 task items
- Create custom labels: "priority: high", "status: in-progress", "type: frontend"
- Apply appropriate labels to your issues
- Create a milestone called "v1.0" and add issues to it
- Assign yourself to 2 of the issues
- Make a code change and commit with "Fixes #1" to close an issue
- Add comments to issues with @mentions and #references
- Try searching:
is:open label:bug assignee:@me - Create an issue template for your repository
Best Practices for Issues
✓ DO:
- Write clear, descriptive titles
- Include reproduction steps for bugs
- Add relevant labels immediately
- Search before creating duplicates
- Use templates when available
- Reference related issues
- Close issues when resolved
- Thank contributors
✗ DON'T:
- Use vague titles like "Bug" or "Problem"
- Create mega-issues tracking multiple things
- Let issues go stale without updates
- Use issues for questions (use Discussions)
- Close issues prematurely
- Be rude or dismissive
- Ignore issue templates
Summary
In this lesson, you learned:
- GitHub Issues track bugs, features, and tasks effectively
- Issue templates standardize bug reports and feature requests
- Labels organize and categorize issues by type, priority, status
- Milestones group issues toward release goals
- Assignees clarify who is responsible for each issue
- Issues can be auto-closed using keywords in commits/PRs
- Powerful search and filtering help find relevant issues
- Projects provide Kanban boards for visual organization
Next Up: In the next lesson, we'll explore Pull Requests - the primary way to propose changes and collaborate on GitHub!