Basic Workflow

1. Create an Issue

• Click the Issues tab in a repo “New issue“

• Optionally use issue templates if defined.

2. Add Metadata

• Apply labels (e.g., bug, feature)

• Set assignees

• Add to milestone or project for tracking.

3. Break Work Down

• Create sub-issues to divide larger tasks.

• Define issue dependencies (blocks/blocked by).

4. Track Progress

• View issues in lists or project boards (tables, Kanban, roadmaps).

• Monitor progress via milestones.

5. Collaborate

• Discuss the issue inside the comments

• @mention reviewers or collaborators

• Reference issues from code/PR comments or commit messages.

6. Close an Issue

• Issues are closed when work is completed or merged via PR using keywords (e.g., fixes #123).

Using GitHub Issues

Creating an Issue

• Steps

1. 1. Navigate to Repository → Issues → New issue

   2. Select an issue template (if configured)

   3. Add:

• • • Clear title

    • Detailed description (Markdown supported)

    • Labels, assignees, projects, milestones

• Tips

  • Reference other issues or PRs using #issue-number

  • Use task lists (- [ ]) for progress tracking

Adding Sub-Issues

Breaking large work into smaller, trackable tasks.

• How

  • Open a parent issue

  • Add sub-issues using the Sub-issues section or issue sidebar

• Benefits

  • Hierarchical tracking

  • Parent issue progress reflects sub-issue completion

Creating Issue Dependencies

Work must happen in a specific order.

• Dependency Types

  • Blocks – the current issue cannot start until another is done

  • Is blocked by – the current issue depends on another

Assigning Issues & Pull Requests

• Rules

  • Assignees must have repository access

  • Multiple assignees are allowed

• Best Practice

  • Assign exactly one owner

  • Use comments for collaboration, not ownership

Editing an Issue

• Editable Fields

  • Title & description

  • Labels

  • Assignees

  • Milestones

  • Issue type (if enabled)

• Notes

  • Edits are logged in the issue timeline

  • Markdown changes update instantly

Viewing All Issues & PRs

• Global View

  • Use github.com/issues to see issues across all repositories

Browsing Sub-Issues

• Where

  • Parent issue → Sub-issues section

  • Repository issue list (if filtering supported)

• Use Case

  • Sprint planning

  • Feature breakdowns

Filtering & Searching Issues

• All open items – Displays every open issue and pull request in the selected scope
• Created by the current user – Shows issues and pull requests authored by the current user
• Assigned to the current user – Highlights items that require the current user’s action or review
• Mentions of the current user – Surfaces issues and pull requests where the current user has been @mentioned

Creating a Branch for an Issue

• How
  • From an issue → Create branch
  • Branch name auto-links to issue
• Benefits
  • Automatic traceability
  • Easier PR linking

Linking a Pull Request to an Issue

A pull request or branch can be linked to an issue to indicate that work on a fix is underway. When the linked pull request or branch is merged, the associated issue is automatically closed, helping keep issue tracking accurate and up to date.

• Automatic Closing Keywords
  • Fixes #123
  • Closes #123
  • Resolves #123
• Result
  • Issue closes automatically when PR is merged into default branch

Slash Commands (Inside Issues & PRs)

• Examples

  • /assign @username

  • /label bug

  • /milestone v1.0

  • /close

• Purpose

  • Faster issue management without UI navigation

Managing Issue Types (Organizations)

• Common Types

  • Bug

  • Feature

  • Task

  • Incident

• Notes

  • Configured at organization level

  • Works alongside labels (not a replacement)