GitLab Milestones
A milestone groups issues and merge requests under one goal and one deadline. Teams use milestones to track a release, a sprint, or a campaign. A progress bar shows how much of the goal is finished.
Picture a road trip with named stops. Each stop is a milestone. Every task you finish brings the car closer to the next stop, and the map shows how far remains.
How Milestones Organize Work
Milestone: Version 2.0 (1 Mar → 30 Apr) ┌────────────────────────────────────────────────┐ │ Issue #12 Add dark mode ✅ closed │ │ Issue #15 Fix login timeout ✅ closed │ │ Issue #18 Export reports to CSV ⏳ open │ │ MR !7 Update payment form ⏳ open │ └────────────────────────────────────────────────┘ Progress: ████████░░░░ 50 percent
Project Milestones and Group Milestones
| Type | Created In | Works For |
|---|---|---|
| Project milestone | One project | Items in that project only |
| Group milestone | A group | Items across every project in the group |
A product made of several repositories fits a group milestone. A single app with one repository fits a project milestone.
Create a Milestone
- Open your project or group.
- Select Plan and open Milestones.
- Select New milestone.
- Type a title such as "Version 2.0".
- Pick a start date and a due date.
- Add a short description of the goal.
- Select Create milestone.
Add Work to a Milestone
From the Issue Page
Open an issue and select Edit beside the Milestone field in the right sidebar. Pick the milestone from the list.
From a Comment
Quick actions save clicks. Type the command in a comment box and submit.
/milestone %"Version 2.0"
From the Issue List
Use bulk edit on the issue list to move many issues into one milestone at once.
Read the Milestone Page
The milestone page gathers everything in one view.
| Area | What It Shows |
|---|---|
| Progress bar | Share of closed issues |
| Start and due dates | The time window for the goal |
| Issues tab | Unstarted, ongoing, and completed issues |
| Merge requests tab | Code changes tied to the goal |
| Participants tab | People assigned to the work |
| Labels tab | Work grouped by label |
Combine Milestones with Boards
Issue boards can filter by milestone. A board for "Version 2.0" shows only the cards that belong to that release.
Board filter: Milestone = Version 2.0 To Do In Progress Review Done ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ #18 │ │ #21 │ │ !7 │ │ #12 │ │ CSV │ │ Search │ │ Payment│ │ Dark │ │ export │ │ filter │ │ form │ │ mode │ └────────┘ └────────┘ └────────┘ └────────┘
Close a Milestone
Open the milestone page and select Close milestone after the deadline or after the last issue closes. Closed milestones stay available for reports. Reopen one when plans change.
Open issues remain in a closed milestone. Move them to the next milestone before closing so that nothing disappears from the plan.
Planning Tips
- Give each milestone one clear goal.
- Set a due date that the team agreed on.
- Size milestones for two to six weeks.
- Review the progress bar in every weekly meeting.
- Move late issues forward with a note that explains the delay.
- Link a release to its milestone when the work ships.
Sample Milestone Plan
| Milestone | Goal | Dates |
|---|---|---|
| Version 1.0 | Launch core features | 1 Jan to 15 Feb |
| Version 1.1 | Fix feedback bugs | 16 Feb to 15 Mar |
| Version 2.0 | Add reports and exports | 16 Mar to 30 Apr |