GitHub 08 🌐 GitHub Issues, Labels, Milestones, and Templates - KandZ

⏱️ Estimated read: 10 min | |

A repository is more than code. It is a workspace where bugs are reported, features are proposed, and work is tracked. GitHub Issues provides the infrastructure for that work: a flexible item type for discussion and planning . But an unstructured issue tracker becomes noise. Labels categorize issues by type and priority. Milestones group them by release or deadline. Templates standardize the information contributors provide before an issue is even opened. Together, these four features transform a list of complaints into a manageable workflow.

Key point: Issues are the unit of work. Labels classify them, milestones group them, and templates shape them at creation. Without all four, the tracker is either chaotic or under-informed.

Why issues, labels, milestones, and templates exist

The tracking problem. Code changes are tracked in commits and pull requests. But not every task is a code change. A bug report needs reproduction steps. A feature request needs a description of the desired behavior. A question needs context. Issues provide a persistent, referenceable object for these discussions, separate from the code itself .

The classification problem. A repository with fifty open issues is unmanageable without categorization. Labels provide that categorization: bug, enhancement, documentation, good first issue. GitHub provides ten default labels in every new repository, and maintainers can add custom ones . Labels are scoped to the repository—adding a label in one repository does not affect another.

The grouping problem. Labels tell you what an issue is. Milestones tell you when it matters. A milestone is a container for issues and pull requests that should ship together. It has a due date, a description, and a completion percentage calculated from the closed items within it . Without milestones, there is no way to answer “what is in the next release?”

The template problem. An issue that says “it doesn’t work” is useless. A template forces the reporter to provide the version, the environment, the steps to reproduce, and the expected behavior. GitHub supports two template mechanisms: the legacy Markdown template (a pre-filled body) and the newer Issue Form (a YAML-defined web form with structured fields) . The form approach is more rigid, but that rigidity is the point—it collects the specific data needed to act.

The trade-off. Templates add friction to issue creation. A contributor with a simple question may be deterred by a form asking for environment variables and log output. The resolution is to provide multiple templates (bug report, feature request) and optionally allow blank issues for cases the templates do not cover.

a. Creating and managing issues

An issue is created from the repository’s Issues tab. The title is required, the body is optional but recommended, and the right sidebar allows assigning the issue to a user, applying labels, linking it to a milestone, and associating it with a project . Issues can also be created from a specific line of code, from a comment on a pull request, or via the GitHub CLI and API.

Issues integrate with the rest of GitHub. Mentioning an issue in a pull request (using fixes #123 or closes #123) links the two. When the pull request merges, the issue closes automatically. This link is visible in both the issue timeline and the pull request conversation .

Title: Bug: Login button unresponsive on mobile

Body:
When viewing the login page on iOS Safari, tapping the login button does nothing.
Expected: form submits.
Actual: no action.

Version: 2.3.1
Browser: Safari 17.2

Sub-issues provide a way to break a large issue into smaller tasks. A parent issue can contain child issues, and the hierarchy is visible in the sidebar. This is useful for epics or multi-step features that do not fit in a single issue .

b. Labels: default set and custom workflow

GitHub provides ten default labels in every new repository :

Label	Purpose
`bug`	Unexpected problem or unintended behavior
`documentation`	Improvements or additions to documentation
`duplicate`	Similar issue, pull request, or discussion
`enhancement`	New feature request
`good first issue`	Suitable for first-time contributors
`help wanted`	Maintainer wants help on this issue
`invalid`	Issue is no longer relevant
`question`	Needs more information
`wontfix`	Work will not continue
`accessibility`	Barrier affecting people with disabilities

The good first issue label has a special function: it populates the repository’s /contribute page, making it easier for new contributors to find entry points . Maintaining this label accurately is part of community management.

Custom labels are created from the Labels page. Anyone with write access can create a label, and anyone with triage access can apply an existing label . Common custom labels include priority: high, needs-design, blocked, and waiting-for-response. The color is cosmetic but useful for visual scanning—red for critical, yellow for waiting, green for ready.

Labels are repository-scoped. A label created in one repository does not appear in another. Organization owners can customize the default label set for repositories within the organization, but individual repositories can still diverge .

c. Milestones and templates

A milestone is created from the Issues or Pull Requests page. It requires a title, and optionally a due date and description. Issues and pull requests are associated with a milestone by selecting it in the right sidebar of the individual item .

The milestone page displays the completion percentage, the number of open and closed items, and a list of all associated issues and pull requests. Open items can be reordered by dragging, which is useful for prioritizing a release . If a milestone exceeds 500 open items, reordering is disabled.

Templates are configured in the repository settings under “Set up templates” in the Issues section . The template chooser appears when a contributor clicks “New issue.” A config.yml file in .github/ISSUE_TEMPLATE customizes this chooser: it can disable blank issues (blank_issues_enabled: false) and redirect certain report types to external links .

The YAML frontmatter of a template sets defaults: title, labels, assignees. The body contains the template text. For structured forms, the body field defines a list of input elements: markdown (static text), input (text field), textarea (multi-line), dropdown (select), checkboxes (multi-select), and upload (file upload) .

name: Bug Report
description: File a bug report.
title: "[Bug]: "
labels: ["bug", "triage"]
body:
  - type: markdown
    attributes:
      value: "Thanks for taking the time to fill out this bug report."
  - type: input
    id: version
    attributes:
      label: Version
      description: What version of the software are you running?
    validations:
      required: true
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Describe the bug and expected behavior.
    validations:
      required: true

The template name must be more than three characters. Once committed to the default branch, the template is available immediately .

Complete Example Session

# ============================================
# PART 1: CREATE A LABEL
# ============================================

# Navigate to Issues → Labels → New label
# Name: priority: high
# Description: Needs immediate attention
# Color: #d73a4a (red)
# Click "Create label"

# ============================================
# PART 2: CREATE A MILESTONE
# ============================================

# Navigate to Issues → Milestones → New milestone
# Title: v2.4.0
# Due date: 2026-12-15
# Description: Authentication overhaul and bug fixes
# Click "Create milestone"

# ============================================
# PART 3: CREATE AN ISSUE
# ============================================

# Click "New issue"
# Title: Login button unresponsive on iOS Safari
# Body: Steps to reproduce, expected vs actual
# Right sidebar: assign to @alex, label "bug", milestone "v2.4.0"
# Click "Submit new issue"

# ============================================
# PART 4: CONFIGURE A TEMPLATE
# ============================================

# Settings → Issues → Set up templates
# Add template → Bug report
# Edit the template to include version and browser fields
# Commit to default branch

# ============================================
# PART 5: CUSTOMIZE THE TEMPLATE CHOOSER
# ============================================

# Create .github/ISSUE_TEMPLATE/config.yml

blank_issues_enabled: false
contact_links:
  - name: Questions
    url: https://github.com/OWNER/REPO/discussions
    about: Please ask questions in Discussions.

# ============================================
# PART 6: CREATE A STRUCTURED ISSUE FORM
# ============================================

# Create .github/ISSUE_TEMPLATE/bug_report.yml

name: Bug Report
description: Report a reproducible bug.
title: "[Bug]: "
labels: ["bug"]
body:
  - type: input
    id: version
    attributes:
      label: Version
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
    validations:
      required: true

# ============================================
# PART 7: LINK ISSUE TO PULL REQUEST
# ============================================

# In the pull request description:
Closes #42
# When merged, issue #42 closes automatically.

# ============================================
# PART 8: FILTER BY LABEL AND MILESTONE
# ============================================

# Issues page → Filters
label:bug milestone:v2.4.0 is:open
# Shows only open bugs in the v2.4.0 milestone.

# ============================================
# PART 9: TRACK MILESTONE PROGRESS
# ============================================

# Issues → Milestones → v2.4.0
# Shows: 12 open, 8 closed, 40% complete
# Drag open issues to prioritize.

The nine parts trace the workflow: creating a label, creating a milestone, creating an issue, configuring a template, customizing the chooser, creating a structured form, linking to a pull request, filtering, and tracking progress.

Quick Reference

Default Labels

Label	Use
`bug`	Unexpected behavior
`enhancement`	New feature
`documentation`	Docs improvement
`good first issue`	New contributor friendly
`help wanted`	Maintainer needs help

Issue Template Types

Type	File Location	Structure
Legacy Markdown	`.github/ISSUE_TEMPLATE/*.md`	Pre-filled body
Issue Form	`.github/ISSUE_TEMPLATE/*.yml`	YAML-defined web form
Chooser Config	`.github/ISSUE_TEMPLATE/config.yml`	Blank issues, contact links

Milestone Fields

Field	Purpose
Title	Release name or sprint identifier
Due date	Deadline for completion
Description	Scope and context
Completion %	Calculated from closed items

Best Practices

✅ Do This:

labels: ["bug", "triage"]
<!-- Apply relevant labels automatically in templates --> # ✅

Closes #42
<!-- Link pull requests to issues for automatic closure --> # ✅

blank_issues_enabled: false
<!-- Force contributors through a template -->              # ✅

❌ Don’t Do This:

# Create label "bug" but forget to apply it
<!-- Unused labels provide no value -->                    # ❌

# Milestone with no due date and no description
<!-- Milestones without scope are just tags -->            # ❌

# Template that requires 20 fields
<!-- Friction deters legitimate reports -->                # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Template not appearing	File not in `.github/ISSUE_TEMPLATE`	Verify path and commit to default branch
`good first issue` not on contribute page	Label name typo or removed	Use exact label name; keep it applied
Milestone percentage incorrect	Issues not associated	Associate each issue manually or via filter
Template name too short	Less than 3 characters	Use a descriptive name
Blank issues still allowed	`config.yml` missing or misconfigured	Set `blank_issues_enabled: false`

Real-World Examples

1. Default Bug Label

Labels: bug, priority: high

2. Release Milestone

Title: v2.4.0
Due: 2026-12-15

3. Good First Issue

Labels: good first issue, documentation

4. Issue Form Field

- type: input
  id: version
  attributes:
    label: Version

5. Auto-Label via Template

labels: ["bug", "triage"]

6. Auto-Close on Merge

Closes #42

7. Filter Open Bugs

label:bug is:open

8. Template Chooser Config

blank_issues_enabled: false

9. Milestone Progress

40% complete (12 open, 8 closed)

10. Assign Issue

Assignee: @alex

Visual

Issue Workflow

┌──────────────────────────────────────────────┐
│  Contributor opens issue                     │
│  (template guides input)                     │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Maintainer triages                          │
│  ├─ Apply labels                             │
│  ├─ Assign to milestone                      │
│  └─ Assign to user                           │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Pull request references issue               │
│  (Closes #42)                                │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  PR merges → issue closes                    │
│  Milestone progress updates                  │
└──────────────────────────────────────────────┘

The template shapes the input. The labels and milestone shape the output.

Label and Milestone Relationship

┌──────────────────────────────────────────────┐
│  Repository                                  │
│                                              │
│  Labels: bug, enhancement, good first issue  │
│  (classify the type of work)                 │
│                                              │
│  Milestones: v2.4.0, v2.5.0                  │
│  (group work by release)                     │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  Issue #42                                   │
│  Labels: bug, priority: high                 │
│  Milestone: v2.4.0                           │
└──────────────────────────────────────────────┘

Labels answer “what kind of work.” Milestones answer “when does it ship.”

Summary

Item	Value
Issue purpose	Track bugs, features, tasks, questions
Default labels	10, including bug, enhancement, good first issue
Label scope	Repository-specific
Milestone purpose	Group issues by release/deadline
Template location	`.github/ISSUE_TEMPLATE/`
Form syntax	YAML with body field types
Auto-close keyword	`Closes #123` in pull request
Good first issue	Populates `/contribute` page

Key takeaways:

Issues are the unit of work. They track bugs, features, and tasks, and integrate with pull requests for automatic closure .
Labels classify issues within a repository. GitHub provides ten defaults; custom labels extend the set. good first issue has special significance for contributor onboarding .
Milestones group issues by release. They display completion percentage and allow drag-and-drop prioritization .
Templates standardize issue creation. Issue Forms use YAML to define structured fields, ensuring contributors provide the information needed to act .
The template chooser is configurable. config.yml can disable blank issues and redirect certain report types to external links .
Linking pull requests to issues automates closure. The Closes #N syntax in a pull request description closes the issue on merge.

Remember: An issue tracker without structure is a complaint box. Labels classify, milestones group, and templates shape. Each feature addresses a specific failure mode: labels solve “I can’t find the bug reports,” milestones solve “what is in the next release,” and templates solve “this report has no useful information.” Configure all three, and the repository becomes manageable.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!