Creating and Managing Milestones

You’ve mastered commits, branches, merges, and even tackles tricky rebases. But as your project grows, so does the chaos: issues pile up, pull requests drift, and releases slip because nobody knows what’s actually blocking the next milestone. Sound familiar? Without a way to group work toward a shared goal, your repository becomes a noisy stream of disconnected tasks. That’s where milestones come in — a built-in Git hosting feature that brings order to your workflow by letting you group issues and pull requests around a common objective, track progress at a glance, and ship with confidence.

The problem this lesson solves

If you’ve ever tried to coordinate a release or a feature without a clear endpoint, you know the pain: tasks are scattered, priorities are fuzzy, and status updates are guesswork. You end up asking “Are we on track?” and getting a shrug. Milestones solve this by giving you a simple, visual way to define a target — like “v1.0 launch” or “Q3 performance sprint” — and automatically track how much of the associated work is complete. Instead of manually chasing issues, you get a live progress bar that updates as you close linked items. This lesson teaches you how to create, populate, edit, and close milestones so you can regain control of your project’s timeline.

The pain is real: teams waste hours in status meetings, and individual contributors lose context on what matters. Milestones turn that around — they’re the missing link between your day-to-day tasks and your long-term goals.

Core concept / mental model

Think of a milestone as a marker on a timeline — a named checkpoint that groups all the work needed to achieve a specific outcome. In Git hosting platforms like GitHub, GitLab, or Bitbucket, a milestone is not a Git object (there’s no git milestone command). Instead, it’s a project management layer on top of your repository’s issues and pull requests. You link work items to a milestone, and the platform calculates progress as you close them.

Analogy: Imagine planning a road trip. Your destination is the milestone. Each issue is a stop along the way — fuel, food, sightseeing. You don’t just drive randomly; you mark your destination on the map, list the stops, and check them off as you go. The milestone is that marked destination, and the checked-off stops are your closed issues.

Key definitions: - Milestone — a named bucket for issues and pull requests, usually tied to a due date. - Open/Closed state — milestones can be open (active) or closed (completed). Closing a milestone is like declaring the destination reached. - Progress percentage — calculated automatically by the platform as (# closed linked items) / (# total linked items). - Due date — optional but recommended; helps teams stay on track.

How it works step by step

The workflow for creating and managing milestones follows a simple loop, whether you’re on GitHub, GitLab, or Bitbucket:

1. Define the outcome. Before you create a milestone, know what success looks like. Is it a release version, a sprint, or a feature batch? Give it a clear, descriptive name.
2. Create the milestone. Navigate to the Issues tab, then Milestones. Click New Milestone, enter a title (and optionally a description and due date), and save.
3. Link work items. While creating or editing an issue or pull request, assign it to the milestone using the Milestone dropdown. Alternatively, on existing items, edit metadata to add the milestone.
4. Track progress. As you close linked items, the milestone’s progress bar fills up automatically. Review the list of open items to see what’s blocking completion.
5. Close the milestone. When all (or enough) linked items are closed and the goal is met, mark the milestone as closed. You can always reopen it if new work appears.
6. Review and adjust. Milestones are live — you can edit the title, due date, or description anytime. If scope changes, unlink items or move them to another milestone.

The cause-and-effect is straightforward: linking items makes progress visible; closing items moves the needle; a closed milestone signals completion to your team.

Hands-on walkthrough

Let’s get practical. These steps assume GitHub, but the patterns apply to GitLab and Bitbucket with minor UI differences. I’ll show you the exact clicks and also a CLI-centric workflow using the gh CLI tool for automation.

1. Creating a milestone via the web UI

1. Go to your repository on GitHub.
2. Click Issues → Milestones.
3. Click New Milestone.
4. Fill in the Title (e.g., v1.0 Release) and optionally a Description and Due date.
5. Click Create milestone.

Your milestone now appears in the list. The progress bar is at 0% because nothing is linked yet.

2. Linking issues and pull requests

When you create a new issue, you’ll see a Milestone dropdown on the right. Select your milestone before submitting. For existing issues, open the issue and click the gear icon next to Milestone to assign it.

Pro tip: Use the gh CLI to assign milestones from the terminal — great for scripting and bulk operations.

3. Automating with gh CLI

If you use GitHub’s official CLI, you can manage milestones without touching the browser. First, ensure you have gh installed and authenticated:

# Install gh (macOS example)
brew install gh

# Authenticate
gh auth login

Now create a milestone with a description and due date:

gh api repos/{owner}/{repo}/milestones -f title="v2.0 Launch" -f description="Core feature set for v2" -f due_on="2025-12-31T23:59:59Z"

Expected output: A long JSON response containing the new milestone’s number, url, etc. You can extract the number for later use.

To list milestones and see progress:

gh api repos/{owner}/{repo}/milestones

Output sample (truncated):

[
  {
    "title": "v2.0 Launch",
    "state": "open",
    "open_issues": 5,
    "closed_issues": 2,
    "progress": 28
  }
]

You can also edit or close a milestone by updating its state:

# Close milestone number 3
gh api -X PATCH repos/{owner}/{repo}/milestones/3 -f state="closed"

4. Tracking progress in the UI

Head back to the Milestones page. You’ll see bars like 28% with counts of open and closed items. Click the milestone to see a filterable list of linked issues and PRs — you can quickly identify what’s still blocking completion.

Compare options / when to choose what

Different platforms implement milestones similarly, but there are nuances. Here’s a quick comparison:

When to choose what: - Use GitHub if you’re already using GitHub Issues and want seamless linking with PRs. The CLI tool is a huge plus. - Use GitLab if you run formal sprints and need burndown charts without extra tools. - Use Bitbucket if your code is there and you plan to use Jira for heavier project management.

Pro tip: Whatever platform you use, keep milestones small and time-boxed (1–2 weeks). Large milestones lose their focus and become mini-backlogs.

Troubleshooting & edge cases

Even with a clear workflow, you’ll hit a few snags. Here are the common ones and how to fix them:

• Progress doesn’t update. Ensure you’re closing the linked issue, not just commenting. Closing a linked PR typically closes the issue automatically only if you use keywords like closes #12 — otherwise, you may need to close issues manually.
• Milestone can’t be closed because unrelated items are linked. Review the list of open items and decide: either close them, unlink them, or move them to another milestone. Remember, you can close a milestone even if not all items are closed — the platform will warn you, but it’s allowed.
• Accidentally edited the due date after start. No problem — milestones are editable. Just update the date if scope shifts; the progress bar is unaffected.
• Multiple milestones with similar names get confusing. Use a naming convention like v1.0, v1.1, Sprint 12, etc. Avoid vague titles like “Release” or “Fix stuff.”
• CLI automation fails with 404. Double-check your repo path and that you have repo scope in gh auth. Also confirm that the milestone title is unique — the API will error otherwise.
• Milestone shows 100% but work continues. It means all linked items are closed, but maybe you forgot to link new tasks. Always scan for unlinked issues at project checkpoints.

What you learned & what's next

You now know how to create a milestone, link issues and PRs, track progress, and close it when the goal is met — both through the web UI and the gh CLI. You also understand the mental model: milestones are a project management layer, not a Git feature, and they bridge your daily tasks with your release goals. You can explain the core idea behind milestones and complete a practical exercise, meeting both learning objectives.

Key takeaways to remember: - Milestones help you group work around a shared outcome and visualize progress automatically. - Creation is platform-specific (GitHub, GitLab, Bitbucket) but follows the same pattern. - Link items at creation time to avoid missing tasks. - Close the milestone only when the goal is truly met; you can always reopen. - Use the gh CLI for automation and scripting.

What’s next? In the next lesson, we’ll explore Releases — how to tag a commit and publish a downloadable snapshot of your project, which pairs perfectly with milestones. You’ll learn how to tie a release to a milestone and deliver value to your users with confidence.

Now go create your first milestone and watch your project’s progress bar turn green!