Get started with GitHub issues

  • 8 minutes

GitHub Issues is the built-in tracking system for tasks, bugs, and feature requests in GitHub repositories. Before you can effectively resolve issues using GitHub Copilot, you need to understand how to work with GitHub Issues effectively.

What are GitHub issues?

GitHub Issues provides a collaborative workspace where teams track work items, document problems, and plan improvements. Each issue functions as a ticket in a tracking system – it can be assigned to team members, categorized with labels, linked to code changes, and enriched with discussions and documentation.

Think of GitHub Issues as a team's intelligent to-do list. Each item holds discussions, code references, and metadata to ensure work doesn't fall through the cracks. For security-focused work, GitHub Issues provides visibility and traceability that helps teams respond to vulnerabilities systematically.

Core components of an issue

Understanding the structure of GitHub Issues helps you read, manage, and resolve them effectively.

Title

The title should be a concise, descriptive summary of the issue. Good titles help team members quickly understand the problem at a glance.

Examples of effective issue titles:

  • "SQL injection vulnerability in product search endpoint"
  • "Weak encryption in user password storage"
  • "Path traversal risk in file upload functionality"

A well-written title immediately communicates both the type of problem (security vulnerability) and its location (product search endpoint).

Description

The description is where the details live. A comprehensive issue description should include the following information:

  • What's happening: A clear explanation of the problem or requirement.
  • Steps to reproduce: For bugs, specific actions that trigger the issue.
  • Expected behavior: What should happen instead?
  • Why it matters: The importance of addressing this issue.
  • Acceptance criteria: How to verify when the issue is resolved.

Here's an example of a well-structured security issue description:

The login authentication function stores user passwords in plaintext in the database.

**Current behavior:**
Passwords are stored directly as strings without hashing or encryption.

**Security impact:**
If the database is compromised, all user passwords are immediately exposed.

**Expected behavior:**
Passwords should be hashed using a secure algorithm (like bcrypt) with appropriate salt before storage.

**Acceptance criteria:**
- Implement bcrypt password hashing.
- Verify no plaintext passwords exist in storage.
- Update authentication to validate against hashed passwords.

A well-written issue is half-fixed. It guides the developer straight to the problem without ambiguity.

Comments

The comments section enables team discussion. Team members can:

  • Ask clarifying questions.
  • Propose potential solutions.
  • Share investigation findings.
  • Reference related code or issues.
  • Document decisions made during resolution.

Comments create a knowledge trail that helps current and future developers understand both the problem and the reasoning behind the solution.

Assignees

The assignee is the person responsible for resolving the issue. Having a clear owner ensures accountability and prevents issues from languishing in the backlog.

Best practice: Always assign one primary owner for an issue. If you're the assignee, you're responsible for driving it to resolution. Being the assignee doesn't mean you work alone – you can collaborate with others – but you own the outcome.

Labels

Labels categorize and prioritize issues. Common labels include:

  • Type labels: bug, enhancement, documentation, security.
  • Priority labels: P0-critical, P1-high, P2-medium, P3-low.
  • Status labels: in-progress, blocked, needs-review.
  • Component labels: backend, frontend, API, database.

Labels can be used to filter and sort issues in lists, making it easier to focus on high-priority or security-related work.

For security issues, labels help teams quickly filter and prioritize vulnerabilities that need immediate attention. A security label combined with P0-critical signals that the issue requires urgent action.

Milestones

Milestones group related issues toward a common goal. For example, a version release or project phase. While not critical for individual issue resolution, milestones help teams coordinate work and track progress toward larger objectives.

Examine the lifecycle of an issue

Issues move through several stages from creation to resolution. Understanding this lifecycle helps you manage issues effectively.

Stage 1: Creation

Issues can be created by developers, testers, or users who identify problems or opportunities for improvement. Security issues might be discovered through:

  • Code reviews.
  • Automated security scans.
  • Penetration testing.
  • User reports.
  • Security audits.

When creating an issue, include sufficient context and acceptance criteria. This sets clear expectations for when the issue is considered resolved.

Stage 2: Triage

During triage, a team lead or designated person:

  • Reviews new issues.
  • Assigns priority levels.
  • Adds appropriate labels.
  • Assigns the issue to a developer.
  • Links related issues or documentation.

High-severity issues, particularly security vulnerabilities, are flagged for immediate attention. Security issues should never sit in a backlog without assessment.

Stage 3: Investigation and discussion

The assigned developer investigates the issue. Developers can complete one or more of the following tasks during their investigation:

  • Ask clarifying questions in comments.
  • Document findings from code analysis.
  • Propose potential solutions.
  • Request additional information.
  • Identify related code areas affected.

This discussion phase ensures that everyone understands the problem before implementing a fix.

Stage 4: Implementation

The developer creates a feature branch and implements the fix. The implementation process typically involves the following tasks:

  • Writing or modifying code.
  • Adding or updating tests.
  • Verifying the fix locally.
  • Preparing a pull request (PR).

Stage 5: Linking commits and pull requests

GitHub automatically connects issues to code changes when you reference them in commit messages or PR descriptions using keywords:

  • Fixes #123
  • Closes #123
  • Resolves #123

Example commit message:

Fix SQL injection vulnerability in search function

Implement parameterized queries to prevent SQL injection attacks.
Add input validation for search parameters.

Fixes #42

Using keywords to reference issues creates traceability between the problem and its solution. When the PR is merged, GitHub automatically closes the referenced issue. This automation ensures issues don't remain open after they're fixed and creates a permanent link between the problem description and the code changes that resolved it.

Stage 6: Closure and verification

When the PR is merged, the issue closes automatically (if properly referenced). If testing reveals the issue isn't fully resolved, it can be reopened for more work.

Best practice: After closing, verify that the acceptance criteria in the original issue description are met. For security issues, consider extra verification through security testing.

Manage GitHub issues in Visual Studio Code

Visual Studio Code integrates directly with GitHub Issues through the GitHub Pull Requests extension. This integration allows you to:

  • View assigned issues without leaving the editor.
  • Create new issues from within Visual Studio Code.
  • Link code changes to issues as you work.
  • Review issue details alongside your code.

To access GitHub Issues in Visual Studio Code:

  1. Install the "GitHub Pull Requests and Issues" extension.
  2. Sign in to your GitHub account.
  3. View issues in the GitHub panel.
  4. Filter by assignee, labels, or milestones.

This tight integration streamlines your workflow by keeping issue context visible while you code.

Why effective issue management matters

Clear issue tracking prevents critical problems from slipping through the cracks, especially in security. Consider these real-world scenarios:

  • Minor issues become major incidents: A "minor-looking" security issue in the backlog can become a serious incident if attackers discover it first. Security issues in GitHub Issues are visible and traceable – use that visibility as an accountability tool.

  • Lost institutional knowledge: When issues are poorly documented or discussions happen outside the tracking system, valuable context disappears. Future developers (including you in six months) might not understand why certain decisions were made.

  • Delayed responses: Without clear priority labels and assignees, critical security vulnerabilities might not receive timely attention.

Embrace issue-driven development: Identify the issue, fix it, verify the fix, close the issue, and move on. This systematic approach ensures completeness and builds confidence in your codebase.

Summary

GitHub Issues provides the foundation for systematic problem-solving in software development. Understanding how to read, interpret, and manage issues effectively is essential before you can resolve them efficiently.