GitLab 07 🦊 Issue Tracking, Epics, Milestones, and Kanban Boards - KandZ

⏱️ Estimated read: 9 min | |

GitLab’s planning tools are hierarchical. An epic groups related issues across projects and time. A milestone groups issues by a deadline or release. An issue is the unit of work. A board is a view of the issues, organized by their status in a workflow. The exam tests this hierarchy and the specific mechanics that link the layers: how an issue is assigned to a milestone, how a milestone is scoped to a project or a group, and how the board columns map to labels. The critical distinction is between the work item (issue) and the container (epic, milestone). The container organizes the work; it does not execute it.

Key point: An epic is a group-level concept that can contain issues from multiple projects. A milestone is scoped to a project or a group and is typically used as a release marker. An issue belongs to one project and can be assigned to one milestone and one or more epics (on paid tiers). A board visualizes issues as cards, grouped by a label or a milestone.

Why the planning hierarchy exists

The multi-project problem. A feature may require work in the frontend project, the backend project, and the documentation project. A milestone in the frontend project cannot contain issues from the backend. An epic, at the group level, can. The epic is the container for cross-project work; the milestone is the container for a release within a single project .

The deadline problem. A milestone has a due date and a completion percentage. It answers the question “what is shipping, and when?” The issue answers “what is the specific task?” The board answers “where is each task in the workflow?” The three views are complementary: the milestone is the schedule, the issue is the unit, and the board is the flow.

The board problem. A kanban board is a visualization of issues grouped by a label. The default board uses the workflow:: scoped labels to define columns. Each column corresponds to a label, and moving a card between columns changes the label. The board is not a separate data store; it is a view of the issues that already exist .

The planning hierarchy problem. Epics contain issues. Issues belong to milestones. Milestones roll up to a completion percentage. Boards show the flow of issues across labels. Each layer answers a different question: the epic answers “what is this initiative?”, the milestone answers “what ships in this release?”, and the board answers “what is the current state of each task?” .

The trade-off. The hierarchy requires setup. Epics must be created before issues can be assigned to them. Milestones must be created before issues can be assigned to them. Boards must be configured with the correct labels. The initial setup cost is offset by the visibility that the hierarchy provides.

a. Creating and managing issues

An issue is created from the project’s Plan → Issues page. The form requires a title, an optional description, and optionally an assignee, a milestone, labels, and a due date.

Plan → Issues → New issue
Title: Fix login timeout
Description: Session expires after 5 minutes instead of 30.
Assignee: alice
Milestone: v2.1
Labels: bug, priority::high
Create issue

The issue description supports Markdown, quick actions, and references. A quick action like /assign @bob assigns the issue when the comment is submitted. A reference like #42 links to another issue. A closing pattern like Closes #42 in a merge request description links the merge request to the issue and closes the issue when the merge request merges .

The issue list supports filtering by label, milestone, assignee, author, and weight. The Weight field is a numeric value that can be summed per milestone, which is used for capacity planning .

b. Milestones and epics

A milestone is created from Plan → Milestones. It has a title, an optional description, a start date, and a due date. Issues are assigned to a milestone from the issue’s right sidebar or in bulk from the issue list.

Plan → Milestones → New milestone
Title: v2.1
Start date: 2026-11-01
Due date: 2026-11-30
Create milestone

The milestone page shows the list of assigned issues and merge requests, the completion percentage, and the time spent. The percentage is calculated from the closed issues. The Burnup and Burndown charts visualize the progress over time.

An epic is created from the group’s Plan → Epics page (available on Premium and Ultimate tiers). It has a title, a description, a start date, and a due date. Issues are assigned to an epic from the issue’s right sidebar. The epic page shows the list of child issues and the aggregate progress.

Group → Plan → Epics → New epic
Title: Multi-region support
Start date: 2026-10-01
Due date: 2027-01-31
Create epic

The epic can contain issues from multiple projects in the group. This is the mechanism for cross-project planning. The milestone, by contrast, is scoped to a single project and is used for release planning within that project.

c. Kanban boards and labels

A board is created from Plan → Boards. The default board is scoped to the project. A group board can aggregate issues from multiple projects. The board displays issues as cards, grouped by a label.

Plan → Boards → New board
Name: Development board
Scope: Project
Create board

The default board columns are defined by the workflow:: scoped labels: workflow::ready for development, workflow::in dev, workflow::in review, workflow::verification, and workflow::production. These labels are created when the board is created, or they can be added manually to an existing board. Dragging a card from one column to another changes the label on the issue.

The board has two modes: the issue board and the epic board. The issue board shows issues. The epic board shows epics as cards, which is useful for tracking initiatives across teams.

The board filters allow the board to show a subset of issues: by milestone, by assignee, by label, or by weight. A milestone-specific board shows only the issues assigned to that milestone, which is the correct view for a release standup.

Complete Example Session

# ============================================
# PART 1: CREATE A MILESTONE
# ============================================

Plan → Milestones → New milestone
Title: v2.1
Due date: 2026-11-30
Create milestone

# ============================================
# PART 2: CREATE AN EPIC
# ============================================

Group → Plan → Epics → New epic
Title: Multi-region support
Start date: 2026-10-15
Due date: 2027-01-31
Create epic

# ============================================
# PART 3: CREATE AN ISSUE
# ============================================

Plan → Issues → New issue
Title: Fix login timeout
Milestone: v2.1
Labels: bug, priority::high
Create issue

# ============================================
# PART 4: ASSIGN THE ISSUE TO THE EPIC
# ============================================

Issue → right sidebar → Epic → Multi-region support

# ============================================
# PART 5: CREATE A BOARD
# ============================================

Plan → Boards → New board
Name: Development board
Create board

# ============================================
# PART 6: CONFIGURE BOARD COLUMNS
# ============================================

Board → Configure board
Add labels: workflow::in dev, workflow::in review
Save

# ============================================
# PART 7: MOVE A CARD
# ============================================

# Drag the issue card from "workflow::in dev" to "workflow::in review"
# The issue's label is updated automatically.

# ============================================
# PART 8: FILTER THE BOARD
# ============================================

Board → Filter → Milestone: v2.1
# Only issues assigned to v2.1 are shown.

# ============================================
# PART 9: CHECK MILESTONE PROGRESS
# ============================================

Plan → Milestones → v2.1
# Shows completion percentage and assigned issues.

The nine parts trace the planning hierarchy: milestone creation, epic creation, issue creation, epic assignment, board creation, board configuration, card movement, board filtering, and milestone progress.

Quick Reference

Planning Objects

Object	Scope	Purpose
Epic	Group	Cross-project initiative
Milestone	Project or group	Release or deadline
Issue	Project	Unit of work
Board	Project or group	Workflow visualization

Issue Labels

Label	Purpose
`bug`	Defect
`feature`	New functionality
`priority::high`	Scoped priority label
`workflow::in dev`	Board column

Board Columns

Label	Column
`workflow::ready for development`	Ready
`workflow::in dev`	In development
`workflow::in review`	In review
`workflow::verification`	Verification
`workflow::production`	Production

Quick Actions

Action	Effect
`/assign @user`	Assign issue
`/milestone %name`	Set milestone
`/label ~bug`	Add label
`/close`	Close issue

Best Practices

✅ Do This:

# Use epics for cross-project initiatives
<!-- Epics span projects; milestones do not -->

# Use milestones for release planning
<!-- Milestones have due dates and completion % -->

# Use scoped labels for board columns
<!-- workflow:: prefix groups columns -->

❌ Don’t Do This:

# Assign issues to multiple milestones
<!-- Each issue belongs to one milestone -->

# Use the same label for priority and workflow
<!-- Scoped labels prevent confusion -->

# Create a board without configuring columns
<!-- The default is empty -->

Common Pitfalls

Pitfall	Why It Happens	Fix
Epic not visible	Tier does not include epics	Use milestone or upgrade tier
Milestone progress not updating	Issue not assigned to milestone	Assign issues in bulk
Board columns empty	Labels not configured	Add `workflow::` labels to the board
Cross-project issue not in epic	Epic is group-scoped	Verify the project is in the group
Card drag not changing label	Board read-only or wrong scope	Verify permissions

Real-World Examples

1. Create Issue

Plan → Issues → New issue
Title: Fix login timeout
Labels: bug, priority::high

2. Assign to Milestone

Issue → right sidebar → Milestone → v2.1

3. Create Milestone

Plan → Milestones → New milestone
Title: v2.1

4. Create Epic

Group → Plan → Epics → New epic
Title: Multi-region support

5. Board Creation

Plan → Boards → New board
Name: Development board

6. Board Columns

Board → Configure board → Add labels

7. Board Filter by Milestone

Board → Filter → Milestone: v2.1

8. Quick Action

/assign @alice

9. Bulk Assign

Issues list → select issues → Edit → Milestone

10. Check Progress

Plan → Milestones → v2.1 → completion %

Visual

Planning Hierarchy

┌──────────────────────────────────────────────┐
│  EPIC (group-level)                          │
│  Multi-region support                        │
└──────────────────┬───────────────────────────┘
                   │
        ┌──────────┴──────────┐
        │                     │
        ▼                     ▼
┌───────────────┐     ┌───────────────┐
│  Issue #42    │     │  Issue #43    │
│  (frontend)   │     │  (backend)    │
└───────┬───────┘     └───────┬───────┘
        │                     │
        └──────────┬──────────┘
                   ▼
┌──────────────────────────────────────────────┐
│  MILESTONE (project-scoped)                  │
│  v2.1                                        │
└──────────────────┬───────────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────────┐
│  BOARD (workflow view)                       │
│  Columns defined by workflow:: labels        │
└──────────────────────────────────────────────┘

Board Column Flow

┌──────────────────────────────────────────────┐
│  workflow::ready for development             │
│  └── Issue card                              │
└──────────────────┬───────────────────────────┘
                   │ drag
                   ▼
┌──────────────────────────────────────────────┐
│  workflow::in dev                            │
│  └── Issue card                              │
└──────────────────┬───────────────────────────┘
                   │ drag
                   ▼
┌──────────────────────────────────────────────┐
│  workflow::in review                         │
│  └── Issue card                              │
└──────────────────┬───────────────────────────┘
                   │ drag
                   ▼
┌──────────────────────────────────────────────┐
│  workflow::production                        │
│  └── Issue card                              │
└──────────────────────────────────────────────┘

Summary

Item	Value
Epic scope	Group (cross-project)
Milestone scope	Project or group
Issue scope	Project
Board	View of issues grouped by label
Default board columns	`workflow::` labels
Issue-milestone relationship	One milestone per issue
Issue-epic relationship	Multiple epics per issue (paid tiers)
Quick actions	`/assign`, `/milestone`, `/label`

Key takeaways:

The planning hierarchy is layered. Epics are for cross-project initiatives. Milestones are for release deadlines. Issues are the unit of work. Boards are the workflow visualization .
An issue belongs to one milestone. The milestone rolls up to a completion percentage. The issue cannot belong to multiple milestones, which is why epics exist for cross-project grouping .
The board is a view, not a data store. Moving a card changes the label on the issue. The board columns are defined by workflow:: scoped labels .
Quick actions automate assignment. /assign, /milestone, and /label in an issue description or comment perform the action when the comment is submitted .
The epic is group-scoped. It can contain issues from multiple projects in the same group. This is the mechanism for cross-project planning.

Remember: The planning hierarchy answers different questions. The epic answers “what is this initiative?” The milestone answers “what ships in this release?” The issue answers “what is the specific task?” The board answers “what is the current state?” Each layer is a different view of the same underlying work. The epic and milestone are containers. The issue is the unit. The board is the flow.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!