GitHub Issues

GitHub Issues is a built-in issue tracking system. It's where teams report bugs, request features, ask questions, and discuss ideas.

What are Issues?

Issues are threaded discussions attached to a repository:

• Bug reports
• Feature requests
• Questions
• Tasks
• Documentation requests
• Any discussion topic

Creating an Issue

From Web UI

1. Go to repository
2. Click "Issues" tab
3. Click "New issue"
4. Fill in title and description
5. Click "Submit new issue"

From GitHub CLI

# Create interactively
gh issue create

# Create with details
gh issue create --title "Bug: Login fails" --body "Description here"

# Create from file
gh issue create --title "New feature" --body-file description.md

Issue Components

Title

Clear, descriptive summary:

✅ Good:

• "Login fails with special characters in password"
• "Add dark mode support"
• "Documentation: Add API examples"

❌ Bad:

• "Bug"
• "It doesn't work"
• "Help"

Description

Use Markdown for formatting:

## Description
Brief description of the issue.

## Steps to Reproduce
1. Go to login page
2. Enter username with @
3. Click submit

## Expected Behavior
Should log in successfully.

## Actual Behavior
Error message appears.

## Environment
- OS: macOS 14.0
- Browser: Chrome 120
- Version: 2.1.0

## Screenshots
![screenshot](url)

Labels

Categorize issues:

Label	Purpose
bug	Something isn't working
feature	New feature request
enhancement	Improvement to existing
documentation	Documentation only
good first issue	Good for newcomers
help wanted	Extra attention needed
duplicate	Already exists
wontfix	Won't be addressed
priority: high	Urgent

Assignees

Who's responsible for the issue.

Milestones

Group issues for a release or sprint.

Projects

Add to a project board (Kanban-style tracking).

Issue Templates

Creating Templates

Create .github/ISSUE_TEMPLATE/bug_report.md:

---
name: Bug Report
about: Report a bug
title: 'Bug: '
labels: bug
assignees: ''
---

## Description
<!-- Clear description of the bug -->

## Steps to Reproduce
1.
2.
3.

## Expected Behavior
<!-- What should happen -->

## Actual Behavior
<!-- What actually happens -->

## Environment
- OS:
- Browser:
- Version:

## Screenshots
<!-- If applicable -->

## Additional Context
<!-- Any other info -->

Template Config

Create .github/ISSUE_TEMPLATE/config.yml:

blank_issues_enabled: false
contact_links:
  - name: Community Support
    url: https://discussions.example.com
    about: Ask questions here

Working with Issues

Commenting

• @ mention people: @username
• Reference other issues: #123
• Reference PRs: #456
• Use Markdown formatting

Linking Issues and PRs

In PR description:

Fixes #123
Closes #456
Resolves #789

When PR merges, these issues close automatically.

Cross-Repository References

owner/repo#123

Reactions

React to issues/comments with:

• 👍 👎 ❤️ 🎉 😕 🚀 👀

Better than "+1" comments!

Issue Management

Searching Issues

is:issue is:open label:bug
is:issue author:username
is:issue assignee:me
is:issue milestone:"v2.0"
is:issue created:>2025-01-01
is:issue updated:>2025-01-01
is:issue no:assignee
is:issue no:label

Filtering

Use the filter bar:

• is:open / is:closed
• label:bug
• author:username
• assignee:username
• milestone:"Sprint 1"

Sorting

Sort by:

• Newest / Oldest
• Most commented
• Recently updated
• Best match (for search)

Closing Issues

Via Web UI

Click "Close issue" button.

Via Commit/PR

git commit -m "Fix login bug

Fixes #123"

Via CLI

gh issue close 123
gh issue close 123 --comment "Fixed in v2.1"

Reopening

Click "Reopen issue" if closed in error.

Issue Best Practices

For Reporters

1. Search first: Check if it already exists
2. Use templates: Fill them out completely
3. Be specific: Exact steps, versions, environment
4. Provide examples: Code, screenshots, logs
5. One issue per topic: Don't combine unrelated things

For Maintainers

1. Respond promptly: Even if just acknowledging
2. Label consistently: Use standard labels
3. Link duplicates: Reference related issues
4. Be welcoming: Encourage contributions
5. Close stale issues: Keep list manageable

Automation

GitHub Actions

Auto-label issues:

# .github/workflows/labeler.yml
name: Issue Labeler
on:
  issues:
    types: [opened]
jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v4

Bots

• Stale bot: Close inactive issues
• First-timers bot: Welcome new contributors
• Auto-assign: Assign based on files changed

Summary

• Issues track bugs, features, and discussions
• Write clear titles and detailed descriptions
• Use labels, assignees, and milestones
• Create templates for consistency
• Link issues to PRs with keywords
• Search and filter to find issues
• Respond promptly and be welcoming

In the next lesson, we'll explore GitHub Projects.