Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท Issues, Projects and Discussions

Labels, Milestones and Issue Templates

Organize issues with labels and milestones, then guide reporters with issue templates and YAML issue forms, a config file for contact links and a pull request template.

A repository with hundreds of issues becomes unusable without structure. Three features give it structure: labels classify issues, milestones group them toward a goal or date, and templates make sure each new issue arrives with the information you need. Together they turn a pile of complaints into a plan.

Labels

A label is a short, colored tag. Every repository starts with a default set: bug, documentation, duplicate, enhancement, good first issue, help wanted, invalid, question and wontfix. You manage them on the Issues tab, under Labels: create, edit the color and description, or delete.

Apply labels from the sidebar of an issue or PR, in bulk from the list (tick several, then Label), or from the CLI: gh issue edit 12 --add-label bug,priority:high.

Designing a label scheme

Use prefixes so labels group together in sorted lists and filters:

Group Examples Question answered
type: type: bug, type: feature, type: docs What kind of work is it?
priority: priority: high, priority: low How urgent?
area: area: api, area: ui Which part of the product?
status: status: needs-info, status: blocked Where is it stuck?
Community good first issue, help wanted Can a newcomer take it?

Keep the list short (a dozen or two). Labels that nobody uses are noise, and good first issue is special: GitHub surfaces those issues to newcomers in its contribute pages.

JS Stand-in: label hygiene check

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Milestones

A milestone groups issues and pull requests under a name, with an optional due date and description: v2.0, Q3 2026, Launch day. The milestone page shows a progress bar (closed items out of all) and lists what is open. Create milestones under Issues > Milestones, and assign items from the sidebar or with gh issue edit 12 --milestone "v2.0".

Use milestones for time- or release-bound scopes: "what must ship in 2.0?". For ongoing prioritization use labels and projects (the next lesson). An issue can have only one milestone. Closing a milestone hides it from the picker without deleting anything.

JS Stand-in: milestone progress

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Issue templates

When someone clicks New issue, GitHub can show a template chooser with options such as Bug report and Feature request. Templates live in .github/ISSUE_TEMPLATE/. There are two kinds.

Markdown templates

A Markdown file with front matter prefills the issue body:

MARKDOWN
---
name: Bug report
about: Something is not working
title: "[Bug] "
labels: ["type: bug", "status: needs-triage"]
---

**What happened?**

**Steps to reproduce**
1.

**Expected behavior**

**Version and environment**

Issue forms (YAML)

An issue form shows real form fields: text boxes, dropdowns, checkboxes. Answers are rendered into a Markdown issue, and required fields cannot be skipped. Save as .github/ISSUE_TEMPLATE/bug.yml:

YAML
name: Bug report
description: Report a problem
title: "[Bug]: "
labels: ["type: bug", "status: needs-triage"]
body:
  - type: markdown
    attributes:
      value: "Thanks for taking the time to report a bug."
  - type: input
    id: version
    attributes:
      label: Version
      placeholder: "2.4.1"
    validations:
      required: true
  - type: dropdown
    id: browser
    attributes:
      label: Browser
      options: [Chrome, Firefox, Safari, Edge, Other]
  - type: textarea
    id: repro
    attributes:
      label: Steps to reproduce
      description: Numbered list, starting from a clean state.
      render: markdown
    validations:
      required: true
  - type: checkboxes
    id: terms
    attributes:
      label: Checks
      options:
        - label: I searched existing issues
          required: true

The element types are markdown (display only), input, textarea, dropdown, checkboxes and upload. Each field except markdown needs an id and attributes.label.

JS Stand-in: validate a submitted form

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The chooser configuration

.github/ISSUE_TEMPLATE/config.yml controls the chooser:

YAML
blank_issues_enabled: false
contact_links:
  - name: Ask a question
    url: https://github.com/octo-org/hello-world/discussions
    about: Questions belong in Discussions, not issues.
  - name: Report a security problem
    url: https://github.com/octo-org/hello-world/security/advisories/new
    about: Please report vulnerabilities privately.

Setting blank_issues_enabled: false forces everybody through a template.

Pull request templates

A file named .github/pull_request_template.md prefills every new PR description (see Pull Requests: The Basics). Keep it short, with a checklist reviewers care about:

MARKDOWN
## What and why

## How was it tested?

## Checklist
- [ ] Tests added or updated
- [ ] Documentation updated
- [ ] No unrelated changes

A repository can also keep several PR templates in .github/PULL_REQUEST_TEMPLATE/ and pick one with a ?template=name.md query parameter.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where are issue templates stored?

    Template files go in .github/ISSUE_TEMPLATE/ in the default branch.
  2. 2. What is an advantage of YAML issue forms over Markdown templates?

    Forms are structured, with validation, and reporters cannot skip required fields.
  3. 3. How many milestones can a single issue belong to?

    An issue or PR has at most one milestone, but any number of labels.
  4. 4. Which setting forces every new issue to use a template?

    Disabling blank issues removes the option to skip the templates.

Summary

  • Labels classify; use prefixes (type:, priority:, area:) and keep the set small.
  • Milestones group work toward a release or date, with a due date and progress bar.
  • Issue templates live in .github/ISSUE_TEMPLATE/; YAML issue forms add structured, validated fields.
  • config.yml adds contact links and can disable blank issues; a pull_request_template.md guides PR descriptions.

Next: GitHub Projects