Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 36 ยท Projects and Merge Requests

Issues, Labels, Milestones and Boards

Plan work in GitLab: write good issues, use labels and scoped labels, milestones, quick actions and issue boards, and link issues to code with closing keywords.

An issue is a unit of work or a conversation: a bug report, a feature request, a question, a task. Issues are the front door of GitLab. Almost every merge request starts from one, and the numbers (#42) appear in commit messages, pipelines and release notes. This lesson shows how to write useful issues and how to organize them with labels, milestones, quick actions and boards.

Anatomy of an issue

Create an issue from the project's Issues page. The form has these parts:

  • Title: one line that states the outcome or the problem ("Checkout fails when the cart has 0 items").
  • Description: Markdown. Explain context, steps to reproduce, expected and actual behavior, and what "done" looks like.
  • Right panel: assignees, labels, milestone, due date, weight, and (in paid tiers) iteration, epic and health status.
  • Confidential checkbox: hides the issue from people below Reporter, useful for security reports.

Issue templates keep descriptions consistent. Put Markdown files in .gitlab/issue_templates/ in your repository (for example Bug.md, Feature.md) and they appear in a dropdown when someone creates an issue. A bug template might contain headings for "Steps to reproduce", "What I expected" and "What happened". Merge requests have the same mechanism under .gitlab/merge_request_templates/.

Besides plain issues, you can create incidents (for outages) and tasks (child items that break a larger issue down). Related issues can be linked with blocks, is blocked by or relates to, and a long issue can carry a task list with checkboxes (- [ ] write tests) whose progress shows in the list view.

Labels

Labels categorize issues and merge requests, and drive filtering and boards. Create them at group or project level (a group label is available to every project in the group). Give each a color and a short description.

A useful starting set: bug, feature, docs, priority::high, priority::low, and a workflow set such as workflow::todo, workflow::doing, workflow::review.

The double-colon syntax creates scoped labels. Only one label per scope can be on an issue at once: adding workflow::review automatically removes workflow::doing. That makes scoped labels perfect for states and priorities, where an item cannot be in two places. (Scoped labels were historically a paid feature; check your tier's documentation for current availability.)

The stand-in below applies labels to an issue and enforces the scope rule, so you can see the behavior.

Python Stand-in: scoped labels replace each other

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that plain labels like bug accumulate, while each scope keeps exactly one value.

Milestones

A milestone groups issues and merge requests toward a goal with an optional start and due date, such as a release (v1.2) or a sprint. The milestone page shows a progress bar and a burndown view in paid tiers. Create milestones in a project or, for cross-project goals, in a group. Select the milestone in the right panel or use a quick action.

Quick actions

Quick actions are slash commands you type in a description or a comment. They run when you save, then disappear from the text. A few you will use constantly:

Command Effect
/assign @ada Assign the issue
/label ~bug ~"needs design" Add labels (quote names with spaces)
/unlabel ~bug Remove a label
/milestone %"v1.2" Set the milestone
/due 2026-12-01 Set a due date
/estimate 4h Record a time estimate
/spend 1h30m Log time spent
/close and /reopen Change the state
/relate #17 Link a related issue

Type / in the comment box to see the available list for the current page. The stand-in parses a block of quick actions in the same spirit, so you can see how arguments with quotes are handled.

Python Stand-in: parse quick actions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The text lines remain as the comment, while the slash lines become changes to the issue.

Boards

An issue board is a Kanban view: each column shows issues that carry a given label, so dragging a card between columns changes its label. A board for a team might have columns for workflow::todo, workflow::doing and workflow::review, plus the built-in Open and Closed lists. Boards can be filtered by assignee, milestone or label, and project boards exist alongside group boards that span many projects. Paid tiers add multiple boards, swimlanes and iteration boards.

flowchart LR
  O["Open"] --> T["workflow::todo"]
  T --> D["workflow::doing"]
  D --> R["workflow::review"]
  R --> C["Closed"]

Dragging a card from one list to the next swaps the scoped label, which is why scoped labels and boards work so well together.

Connecting issues to code

You can create a branch and merge request straight from an issue (the Create merge request button). The branch is named after the issue number and title, such as 42-fix-checkout-crash. When the merge request is merged into the default branch, GitLab closes the issue if the description or a commit message used a closing keyword: Closes #42, Fixes #42, Resolves #42. The next lesson covers this in detail.

Other tips for healthy issue tracking:

  • One problem per issue. If a thread starts covering three topics, split it.
  • Write acceptance criteria as a checklist so reviewers know what done means.
  • Keep the label set small and documented in the project's README or handbook.
  • Triage regularly: filter for issues with no label, no assignee or no milestone.
  • Use /spend and /estimate only if you actually review the numbers.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is special about a label named priority::high?

    The double colon makes a scoped label. Adding another label in the same scope replaces the previous one.
  2. 2. Which quick action sets the due date?

    /due sets a due date; /estimate records time and /milestone selects a milestone.
  3. 3. What happens when you drag a card between two label-based board lists?

    Label lists are driven by labels, so moving a card removes the old list's label and adds the new one.
  4. 4. Where do issue templates live in a repository?

    GitLab reads Markdown templates from .gitlab/issue_templates/ at the repository root.

Summary

  • Issues track bugs, features and tasks; templates make them consistent.
  • Labels classify; scoped labels (scope::value) allow only one value per scope.
  • Milestones group work toward a goal and a date.
  • Quick actions such as /assign, /label, /milestone and /close speed up editing.
  • Boards turn labels into Kanban columns, and closing keywords link issues to merged code.

Next: Merge Requests Basics