GitLab Labels and Templates

Labels sort issues and merge requests into groups. Templates give every new issue or merge request a ready-made structure. Labels answer the question "what kind of work is this?" Templates answer the question "what details do we need?"

Imagine a mailroom. Colored stickers tell staff which parcels are urgent, fragile, or international. A printed form at the counter makes sure every sender fills in the same fields.

What a Label Looks Like

  Issue #42  Login button does not respond

  [bug]  [high-priority]  [frontend]
   red       orange          blue

Project Labels and Group Labels

TypeVisible InBest For
Project labelOne projectLabels that fit a single repository
Group labelEvery project in the groupShared names such as bug or documentation

Group labels keep names and colors identical across projects, so filters work everywhere.

Create a Label

  1. Open your project and select Manage and open Labels.
  2. Select New label.
  3. Type a name such as "bug".
  4. Add a short description.
  5. Pick a background color.
  6. Select Create label.

Apply Labels

Open any issue or merge request and use the Labels field in the right sidebar. A quick action does the same job from a comment.

/label ~bug ~frontend
/unlabel ~frontend

A Practical Label Set

GroupLabelsPurpose
Typebug, feature, documentationKind of work
Priorityurgent, high, normal, lowOrder of attention
Areafrontend, backend, databaseOwning team
Statusin-progress, blocked, needs-reviewCurrent stage

Find Work with Label Filters

The issue list accepts a filter such as Label = bug. Combine several filters to narrow the list.

  Filter:  Label = bug   AND   Label = urgent   AND   Assignee = Riya

  Results:
  #42  Login button does not respond
  #57  Payment page shows blank screen

Use Labels as Board Columns

An issue board turns labels into columns. Dragging a card across columns swaps its label automatically.

  Open        │  in-progress  │  needs-review  │  Closed
  ────────────┼───────────────┼────────────────┼─────────
  #61         │  #58          │  #52           │  #49
  #63         │  #60          │                │  #50

Description Templates

A template is a Markdown file stored in the repository. GitLab loads it into the description box when someone starts a new issue or merge request.

  Repository root:
  └── .gitlab/
      ├── issue_templates/
      │   ├── Bug.md
      │   └── Feature.md
      └── merge_request_templates/
          └── Default.md

Bug Report Template

Save this text as .gitlab/issue_templates/Bug.md.

## Summary
Describe the problem in one or two sentences.

## Steps to Reproduce
1. Open the page
2. Select the button
3. Observe the result

## Expected Result
Describe what should happen.

## Actual Result
Describe what happens.

## Environment
Browser, device, and app version.

/label ~bug

The last line is a quick action. GitLab applies the bug label as soon as the issue is created.

Merge Request Template

Save this text as .gitlab/merge_request_templates/Default.md.

## What Changed
Summarize the change.

## Why
Link the related issue, for example Closes #42.

## Checklist
- [ ] Tests added or updated
- [ ] Documentation updated
- [ ] Pipeline passes

The default template loads into every new merge request without manual selection.

Choose a Template While Creating an Issue

Open Plan → Issues → New issue. A Choose a template dropdown appears above the description box. Pick Bug or Feature to fill the form.

Habits That Keep Labels Useful

  • Limit the label list to what the team uses weekly.
  • Delete or merge labels that overlap in meaning.
  • Write a one-line description for each label.
  • Reserve red for urgent or broken items.
  • Review the label list every quarter.