GitLab Issues and Boards

Issues are the task cards of GitLab. Every bug report, feature request, or improvement idea becomes an issue. Issue boards then arrange those issues visually so teams can see work progress at a glance.

What an Issue Is

An issue is a structured conversation tied to a specific piece of work. Think of it as a sticky note on a whiteboard — except it stores comments, files, due dates, and a full history of activity.

  Issue #42: Search bar returns no results for short words
  ─────────────────────────────────────────────────────────
  Opened by: Arjun          Label: bug, high-priority
  Assigned to: Riya         Milestone: v2.1 release
  Due date: Dec 15          Status: Open
  ─────────────────────────────────────────────────────────
  Description: When the user types 1–2 characters, the
  search returns an empty list even for valid matches.

  Steps to reproduce:
  1. Open the home page
  2. Type "ab" in the search bar
  3. Observe: no results appear

  Comments:
  Riya: Confirmed. The API filters results with length < 3.
  Arjun: Fix is ready in MR #48. Closes #42.
  ─────────────────────────────────────────────────────────

Creating an Issue

Go to Issues → New Issue. Fill in the title, description, assignee, label, and milestone. A clear title like "Search bar ignores 1–2 character queries" is more useful than "Search broken".

Issue Fields and Their Purpose

Labels — Colour-Coded Categories

Labels tag issues so you can filter and group them. Each label has a name and a colour. Create labels at Issues → Labels → New Label.

  🔴 bug           → something is broken
  🟢 feature       → new capability request
  🔵 documentation → needs docs update
  🟡 help wanted   → open for anyone to pick up
  🟣 in review     → code review in progress

You can apply multiple labels to one issue. An issue that adds a new feature but also needs docs might carry both feature and documentation.

Milestones — Grouping Issues by Release

A milestone groups issues into a sprint or release. It shows a progress bar based on how many issues are open vs closed.

  Milestone: v2.1 Release (due Dec 20)
  ────────────────────────────────────────
  Progress: ████████░░  8 of 10 issues closed

  Open issues:
  #42 Search bar bug (Riya)
  #51 Dark mode flicker (Arjun)

  Closed issues:
  #33 #35 #38 #40 #44 #46 #48 #49

Issue Boards — The Visual Workflow

An issue board is a Kanban-style board where each column represents a stage of work. Issues move from left to right as they progress.

  Open          │ In Progress  │ In Review    │ Done
  ──────────────┼──────────────┼──────────────┼──────────────
  #55 New nav   │ #42 Search   │ #48 Login    │ #33 Header ✅
  #57 Dark mode │ #50 API fix  │              │ #35 Footer ✅
  #59 CSV export│              │              │

Drag a card from one column to the next. GitLab automatically applies the column's label to that issue.

Creating a Board

Go to Issues → Boards. A default board with Open and Closed columns exists in every project. Click Create list to add a new column tied to a label.

Scoped Labels for Exclusive States

Scoped labels use the format scope::value. GitLab enforces that only one label per scope can be active on an issue at a time — like radio buttons.

  Labels: status::open, status::in-progress, status::done

  An issue can have status::in-progress OR status::done
  but NOT both at the same time.

This prevents an issue from showing "in-progress" and "done" simultaneously.

Filtering and Searching Issues

The issue list supports powerful filters. Click the search bar above the list to filter by:

• Assignee ("assigned to me")
• Label (one or many)
• Milestone
• Author
• Due date range
• Text in title or description

Linking Issues to Merge Requests

Type Closes #42 in a merge request description. GitLab shows the linked MR inside issue #42 under "Related merge requests". When the MR merges, issue #42 closes automatically.

Issue Templates

Create a file at .gitlab/issue_templates/Bug_Report.md. Anyone opening a new bug report selects this template and GitLab pre-fills the description with your structured format.

  Bug_Report.md template content:
  ────────────────────────────────
  **Describe the bug**
  A clear description of what is wrong.

  **Steps to reproduce**
  1.
  2.
  3.

  **Expected behaviour**

  **Screenshots**

Confidential Issues

Mark an issue as confidential by checking the box when creating it. Only project members with Reporter role or higher can see confidential issues. Use this for security vulnerabilities or sensitive customer reports.