Let’s build a clear picture before looking at any of its individual parts.

An issue is a way of tracking a specific piece of work, a bug, or an idea within a repository, and a pull request proposes a specific set of code changes. On any active project, there can be dozens or hundreds of these floating around individually. A milestone is a named collection that groups a specific subset of these issues and pull requests together, representing everything needed to reach one particular, meaningful goal — such as a version release, a project phase, or a planned deadline.

Once issues and pull requests are attached to a milestone, GitHub automatically calculates and displays how many of them are still open versus already closed, giving an instant, visual sense of how close that milestone is to being fully complete. This transforms an otherwise abstract question — “how’s the release coming along?” — into something concrete and immediately checkable.

With that foundational picture in place, let’s define the vocabulary that explains exactly how milestones are structured.

A handful of terms make the entire milestone concept far easier to follow.

With this vocabulary settled, let’s trace exactly what happens internally as issues and pull requests move through a milestone’s lifecycle.

This is the core mechanic — how a milestone’s progress actually gets calculated and kept current.

flowchart TD
    A[Create milestone with title and due date] --> B[Attach relevant issues and pull requests]
    B --> C[Work happens on individual items]
    C --> D[Items get closed one by one]
    D --> E[Progress bar updates automatically]
    E --> F{All items closed?}
    F -- Not yet --> C
    F -- Yes --> G[Milestone manually closed as complete]
        

Zooming out from a single milestone, let’s see how they typically flow, one after another, across a project’s ongoing timeline.

Active projects rarely have just one milestone — they typically have a sequence of them, representing successive goals over time, such as one milestone per planned release. As one milestone closes, attention naturally shifts to the next one, with new issues and pull requests continuously being created and assigned to whichever upcoming milestone they’re relevant to.

flowchart LR
    A[Milestone: Version 1.0] --> B[Closed once complete]
    B --> C[Milestone: Version 1.1]
    C --> D[Closed once complete]
    D --> E[Milestone: Version 1.2]
    E --> F[Ongoing work continues]
        

This ongoing rhythm gives a project a genuine sense of momentum, visible not just in a single snapshot but across the whole history of completed and upcoming checkpoints. Looking back at a series of closed milestones tells a story of what the team has actually accomplished, phase by phase, far more clearly than a flat, undifferentiated list of every issue ever created.

Both milestones and labels help organize issues and pull requests, so the distinction between them is worth being precise about.

Milestones are also frequently confused with project boards, another organizational tool serving a genuinely different purpose.

Understanding exactly what the progress bar represents avoids a common source of confusion.

A milestone’s progress percentage is calculated purely by counting how many of its attached issues and pull requests are currently closed, divided by the total number attached. It does not account for how large, complex, or time-consuming any individual item actually is — one enormous, difficult issue and one trivial, five-minute issue count exactly the same toward that percentage.

While entirely optional, a milestone’s due date adds a genuinely useful time dimension to tracking progress.

When a due date is set, GitHub can clearly indicate whether a milestone is on track, approaching its deadline, or already overdue, based purely on the current date compared to that target. This turns a milestone from a simple progress tracker into something closer to a lightweight deadline management tool, without requiring any separate scheduling system.

As a project matures, thoughtful organization of multiple milestones becomes genuinely important.

Whichever pattern a team chooses, consistency matters more than the specific choice itself — a predictable naming and organizational convention makes it far easier for anyone browsing the repository to understand what each milestone represents at a glance.

Beyond the simple progress bar, several ways exist to keep a closer eye on how a milestone is actually progressing.

Milestones bring genuine clarity to tracking progress, alongside a few limitations worth being aware of.

Because a milestone’s value depends entirely on how accurately it’s maintained, a handful of genuine pitfalls deserve attention.

A few recurring habits separate teams that keep milestones genuinely useful from teams that let them quietly lose meaning.

A concise set of habits keeps milestones a genuinely trustworthy, useful part of a project’s planning process.

Milestones aren’t a niche feature — they quietly support how many teams communicate progress, both internally and externally.

No, an issue or pull request can only be attached to one milestone at a time, which is one of the key differences from labels covered earlier.

No, closing the milestone itself is a separate, deliberate action, giving the team a chance to confirm the goal is truly complete before marking that checkpoint reached.

No, a due date is entirely optional. Many teams use milestones purely for grouping and progress tracking without attaching any specific deadline at all.

No, as covered earlier, every attached item counts equally toward the percentage regardless of its actual size or complexity.

Yes, a milestone that was closed can typically be reopened if it turns out additional work related to that same goal is genuinely still needed.

A milestone is a named checkpoint grouping together the specific issues and pull requests needed to reach one meaningful goal, giving a project an instant, visual sense of progress through an automatically calculated completion percentage. Distinct from labels, which categorize items without measuring progress, and from project boards, which track detailed workflow stages, a milestone answers one focused question well: how close are we to this particular target? Used thoughtfully — scoped realistically, kept accurate, and paired with genuine judgment beyond the raw percentage — milestones become a simple, powerful way for teams to communicate progress clearly, both to themselves and to everyone watching from the outside.