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
- Go to repository
- Click "Issues" tab
- Click "New issue"
- Fill in title and description
- 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

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:closedlabel:bugauthor:usernameassignee:usernamemilestone:"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
- Search first: Check if it already exists
- Use templates: Fill them out completely
- Be specific: Exact steps, versions, environment
- Provide examples: Code, screenshots, logs
- One issue per topic: Don't combine unrelated things
For Maintainers
- Respond promptly: Even if just acknowledging
- Label consistently: Use standard labels
- Link duplicates: Reference related issues
- Be welcoming: Encourage contributions
- 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.
التالي · الدرس 34 من 40
GitHub Projects
قراءة 4 دقيقة
أنهيت 33 من 40 درسًا

اسأل Byte عن هذا الدرس
محادثة خاصة حول هذا الدرس. قرأ Byte الدرس كاملًا، ويجيب خلال ثوانٍ، ويُظهر القسم الذي تأتي منه كل إجابة. يمكنك السؤال بأي لغة.
الأسئلة والأجوبة
أسئلة عامة حول هذا الدرس. يجيب AI Tutor فورًا بلغتك، ويراجع فريق FreeAcademy الإجابات، ويمكن لكل المتعلمين قراءتها.

