GitHub Issues and Project Tracking

Build the mental model

An issue is GitHub's unit for tracking anything that needs attention but is not yet code: a bug report, a feature request, a task, or an open discussion.

Unlike a pull request, an issue does not contain a branch or commits — it is just a discussion thread with a title, a description, and a status of open or closed, though GitHub can link the two together.

A well-written issue follows a predictable shape, and following it saves everyone time.

GitHub layers lightweight organization on top of this.

• Labels — categorize an issue at a glance (bug, enhancement, documentation, good first issue) and let you filter a busy repository
• Assignees — mark who is responsible, avoiding duplicated work
• Milestones — group related issues and pull requests toward a shared deadline or release

None of these are mandatory, but on any repository with more than a couple of contributors, they are what keeps work from becoming untraceable.

ISSUE LIFECYCLE
---------------
opened --> labeled/assigned --> in progress --> linked PR --> closed
  |              |                    |              |            |
title +      bug/enhancement     someone owns   "Closes #12"   merged PR
description   milestone set          it          in a commit   auto-closes

Connect it to a real scenario

Nothing about browsing or filing issues happens in a terminal, but one small connection to local Git is worth knowing: commit messages and pull request descriptions can reference an issue by number, and specific keywords — Closes, Fixes, or Resolves followed by #<number> — get special treatment.

That link is permanent and searchable later, which is why searching commit history for an issue number, as shown below, is a genuinely useful habit even outside GitHub's website.

On the issue itself, expect to see the description at the top, followed by a comment thread below it where discussion happens over time, current labels and the assignee shown in a sidebar, and — once work starts — a linked pull request appearing automatically the moment someone opens one referencing that issue number, before the issue is even closed.

• An issue is GitHub's tracking unit for anything needing attention that isn't yet code
• A good issue includes Problem, Expected, Actual, Steps to reproduce, and Environment
• Labels, Assignees, and Milestones are lightweight tools for organizing a busy repository

Try the working example

git init -q -b main
git config user.name "Thuta Learner"
git config user.email "learner@example.com"

cat > logger.js <<'EOF'
function log(value) {
  console.log(value.toUpperCase());
}
EOF
git add logger.js
GIT_AUTHOR_DATE="2026-01-01T09:00:00" GIT_COMMITTER_DATE="2026-01-01T09:00:00" \
  git commit -m "Add logger"

cat > logger.js <<'EOF'
function log(value) {
  if (value === undefined || value === null) return;
  console.log(value.toUpperCase());
}
EOF
git add logger.js
GIT_AUTHOR_DATE="2026-01-01T10:00:00" GIT_COMMITTER_DATE="2026-01-01T10:00:00" \
  git commit -m "Fixes #12: guard against undefined input in logger"

git log --oneline --grep="#12"

git log --oneline --grep="#12" ->
790939a Fixes #12: guard against undefined input in logger

On GitHub, merging a pull request whose commit or description contains a phrase like "Fixes #12" automatically closes issue #12 and adds a note on the issue linking back to this commit and pull request — a behavior specific to GitHub's web platform, not something git itself does.

GitHub Docs: Creating an issue — Git & GitHub