ContextQMD
Back to Gitlabhq

Work items

doc/user/work_items/_index.md

18.11.28.0 KB
Original Source

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Work items are the core elements for planning and tracking work in GitLab. Planning and tracking product development often requires breaking work into smaller, manageable parts while maintaining connection to the bigger picture. Work items are designed around this fundamental need, providing a unified way to represent units of work at any level, from strategic initiatives to individual tasks.

The hierarchical nature of work items enables clear relationships between different levels of work, helping teams understand how daily tasks contribute to larger goals and how strategic objectives break down into actionable components.

This structure supports various planning frameworks like Scrum, Kanban, and portfolio management approaches, while giving teams visibility into progress at every level.

Work item types

GitLab supports the following work item types:

  • Issues: Track tasks, features, and bugs.
  • Epics: Manage large initiatives across multiple milestones and issues.
  • Tasks: Track small units of work.
  • Objectives and key results: Track strategic goals and their measurable outcomes.
  • Test cases: Integrate test planning directly into your GitLab workflows.

View all work items

{{< history >}}

{{< /history >}}

The Work items list is the central place to view and manage all work item types (such as issues, epics, and tasks) for a project or group. Use this view to understand the full scope of work in your project or group and prioritize effectively.

In earlier versions of GitLab, issues and epics had separate list pages under Plan > Issues and Plan > Epics. In GitLab 18.10 and later, these pages are replaced by Plan > Work items, which consolidates all work item types in a single view. If you had pinned Issues or Epics in the sidebar, Work items is pinned in their place. URLs that contain /epics/:iid or /issues/:iid automatically redirect to /work_items/:iid.

To view work items for a project or group:

  1. In the top bar, select Search or go to and find your project or group.
  2. Select Plan > Work items.

Filter work items

The Work items list shows all work item types by default. To view a specific type (for example, only issues or only epics), use the Type filter.

To filter the work items list:

  1. At the top of the page, from the filter bar, select a filter, operator, and its value. For example, to view only epics, select the filter Type, operator is, and value Epic.
  2. Optional. Add more filters to refine your search.
  3. Press <kbd>Enter</kbd> or select the search icon ({{< icon name="search" >}}).

Available filters

{{< history >}}

  • Filtering by description introduced in GitLab 18.3.

{{< /history >}}

These filters are available for work items:

  • Assignee
    • Operators: is, is not one of, is one of
  • Author
    • Operators: is, is not one of, is one of
  • Confidential
    • Values: Yes, No
  • Contact
    • Operators: is
  • Status
    • Operators: is
  • Health status
    • Operators: is, is not
  • Iteration
    • Operators: is, is not
  • Label
    • Operators: is, is not one of, is one of
  • Milestone
    • Operators: is, is not
  • My reaction
    • Operators: is, is not
  • Organisation
    • Operators: is
  • Parent
    • Operators: is, is not
    • Values: Any Issue, Epic, Objective
  • Release
    • Operators: is, is not
  • Search within
    • Operators: Titles, Descriptions
  • State
    • Values: Any, Open, Closed
  • Type
    • Values: Issue, Incident, Task, Epic, Objective, Key Result, Test case
  • Weight
    • Operators: is, is not

To access filters you've used recently, on the left side of the filter bar, select the Recent searches ({{< icon name="history" >}}) dropdown list.

Sort work items

{{< history >}}

  • Sorting by status introduced in GitLab 18.5 with a flag named work_item_status_mvc2. Enabled by default.
  • Sorting by status generally available in GitLab 18.6. Feature flag work_item_status_mvc2 removed.

{{< /history >}}

Sort the list of work items by the following:

  • Created date
  • Updated date
  • Start date
  • Due date
  • Title
  • Status
  • Weight

To change the sorting criteria:

  • On the right of the filter bar, select the Created date dropdown list.

To toggle the sorting order between ascending and descending:

  • On the right of the filter bar, select Sort direction ({{< icon name="sort-lowest" >}} or {{< icon name="sort-highest" >}}).

For more information about sorting logic, see sorting and ordering issue lists.

Configure list display preferences

{{< history >}}

{{< /history >}}

Customize how work items are displayed on the list pages by showing or hiding specific metadata fields and configuring view preferences.

GitLab saves your display preferences at different levels:

  • Fields: Saved per namespace. You can have different field visibility settings for different groups and projects based on your workflow needs. For example, you can show assignee and labels in one group or project, but hide them in another.
  • Your preferences: Saved globally across all projects and groups. This ensures consistent behavior for how you prefer to view work items.

To configure display preferences:

  1. In the top bar, select Search or go to and find your group.
  2. Select Plan > Work items.
  3. On the right of the filter bar, select Display options ({{< icon name="preferences" >}}).
  4. Under Fields, turn on or turn off the metadata you want to display:
    • Status (for issues)
    • Assignee
    • Labels
    • Weight (for issues)
    • Milestone
    • Iteration (for issues)
    • Dates: Due dates and date ranges
    • Health: Health status indicators
    • Blocked/Blocking: Blocking relationship indicators
    • Comments: Comment counts
    • Popularity: Popularity metrics
  5. Under Your preferences, turn on or turn off Open items in side panel to choose how epics open when you select them:
    • On (default): Items open in a drawer on the right side of the screen.
    • Off: Items open in a full page view.

Your preference is saved and remembered across all your sessions and devices.

Work item Markdown reference

{{< history >}}

{{< /history >}}

You can reference work items in GitLab Flavored Markdown fields with [work_item:123]. For more information, see GitLab-specific references.