GitLabels & Milestones

Labels & Milestones

Labels and milestones are the two oldest organisational tools in GitHub. Labels are coloured tags you attach to issues and PRs — type, priority, area, status. Milestones are deadline-style groupings — “v2.0 release” or “Q3 roadmap”. Together they take you a long way before you ever need a heavier project management tool.

Labels: the basics

A label has a name, a colour, and an optional description. Anyone with write access can attach labels to issues and PRs from the sidebar.

GitHub’s default labels

  • bug — something’s broken.

  • documentation — docs change needed.

  • duplicate — already filed elsewhere.

  • enhancement — feature request.

  • good first issue — picked up by GitHub’s “contribute” recommendations.

  • help wanted — maintainer signal that contributions are welcome.

  • invalid — not a real issue.

  • question — support, not a bug.

  • wontfix — out of scope, not planned.

Tip
Don’t feel locked into the defaults. Most projects rename `enhancement` → `feature` because it reads better, and add `breaking-change` for changelog automation.
A useful label taxonomy

The trick is grouping labels by facet so a single issue can have one label from each group. A common scheme:

Facet

Examples

Purpose

Type

bug, feature, docs, chore

What kind of work

Priority

p0, p1, p2, p3

How urgent

Area

frontend, backend, infra, design

Which part of the codebase

Status

needs-triage, in-progress, blocked

Where in the workflow

Difficulty

good first issue, advanced

For new contributors

Meta

duplicate, wontfix, question

Resolution reason

Picking colour by facet helps visual scanning: type=blue, priority=red, area=purple, status=green, meta=grey.

Creating and editing labels

Path

Text
Repo → Issues tab → Labels → New label
       └─ Name, Description, Colour (hex or picker)

GitHub CLI

Bash
gh label list
gh label create p0 --color "B60205" --description "Drop everything"
gh label edit bug --color "D93F0B"
gh label delete wontfix
Common label patterns

  • good first issue — a curated list of starter tasks. GitHub surfaces these to first-time contributors.

  • help wanted — broader signal that the maintainer welcomes contributions.

  • needs-triage — auto-applied by issue templates; removed once labelled properly.

  • needs-reproducer — bug report without steps; nudges the reporter.

  • do-not-merge — visible block on a PR while a discussion is ongoing.

Bulk-applying labels

Tag every open issue matching a query

Bash
gh issue list --label needs-triage --json number --jq '.[].number' \
  | xargs -I{} gh issue edit {} --add-label "p2"

Useful for end-of-sprint clean-ups, mass priority bumps, or migrating to a new label taxonomy.

Label sync across repos

For orgs with many repos, keep labels consistent with a sync tool. Popular choices:

  • github-label-sync — define labels in a YAML file, sync to one or many repos.

  • actions/labeler — auto-apply labels to PRs based on changed file paths.

  • release-drafter — uses labels to generate changelog entries.

.github/labeler.yml — auto-label PRs by path

YAML
frontend:
  - changed-files:
      - any-glob-to-any-file:
          - "src/components/**"
          - "src/pages/**"

backend:
  - changed-files:
      - any-glob-to-any-file:
          - "server/**"
          - "src/api/**"

docs:
  - changed-files:
      - any-glob-to-any-file:
          - "**/*.md"
          - "docs/**"
Milestones

A milestone is a named bucket with an optional due date. Each issue or PR can belong to exactly one milestone. The milestone page shows progress as a percentage of closed items.

  • Path: Issues → Milestones → New milestone.

  • Use for: releases (v2.4.0), sprints (Sprint 23), themes (Q3 Reliability).

  • Auto-closed when all items inside close (configurable).

  • Filter the Issues list by milestone to get a release burndown.

CLI for milestones

Bash
gh api repos/acme-co/widget/milestones                # list
gh api repos/acme-co/widget/milestones --method POST -f title="v2.4.0"
gh issue edit 142 --milestone "v2.4.0"
Roadmaps and projects

For heavier planning, GitHub also offers Projects — Kanban/Spreadsheet/Roadmap views across one or many repos, with custom fields (status, sprint, story points, owner). Projects can pull in any issue or PR and stay in sync as their state changes. Worth a look once labels + milestones stop scaling.

Common pitfalls

  • Label sprawl — 80 labels nobody understands. Prune quarterly.

  • Indistinct colours — bug and bugged in similar reds is confusing. Pick distinct hues.

  • Per-repo labels in an org — priority/p0 here, prio-p0 there. Sync them.

  • Milestones that never close — set realistic due dates and honour them, or skip them.

Labels are taxonomy; milestones are time
Labels answer “what kind of work is this?” Milestones answer “when are we doing it?” Mixing the two (`milestone: bugs`, `label: v2.4`) leads to systems nobody understands. Keep the facets clean.
Tip
Document your label taxonomy in a `CONTRIBUTING.md` section. New contributors and new teammates inherit the scheme without having to reverse-engineer it from existing issues.