Work items

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. With work items, you can organize your team’s work using common structures that support various planning frameworks including Scrum, Kanban, and portfolio management approaches.

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

To organize work items (like issues, epics, and tasks) side-by-side, use the consolidated work items view. This view helps you understand the full scope of work, and prioritize effectively.

When you enable this feature, it:

• Removes Plan > Issues and Plan > Epics from the left sidebar in groups and projects.
• Adds Plan > Work items to the left sidebar.
• Pins Work items on the left sidebar for projects and groups, if you had previously pinned Plan > Issues or Plan > Epics.
• Removes Settings > Issues from the left sidebar in groups.
• Adds Settings > Work items to the left sidebar in groups.

To view work items for a project or group:

1. On the left sidebar, select Search or go to and find your project or group. If you’ve turned on the new navigation, this field is on the top bar.
2. Select Plan > Work items.

Filter work items

On the Work items page, you can use filters to narrow down the list:

1. At the top of the page, from the filter bar, select a filter, operator, and its value.
2. Optional. Add more filters.
3. Press Enter or select the search icon .

Available filters

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 ( ) dropdown list.

Sort work items

Sort the list of work items by the following:

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

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 ( or ).

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

Configure list display preferences

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. On the left sidebar, select Search or go to and find your group. If you’ve turned on the new navigation, this field is on the top bar.
2. Select Plan > Epics or Plan > Issues.
3. In the upper-right corner, select Display options ( ).
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

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

Related topics

• Linked issues
• Linked epics
• Issue boards
• Labels
• Iterations
• Milestones
• Custom fields