Work items

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

Work items include the types: Issue, Incident, TestCase, Requirement, Task, Ticket, Objective, KeyResult, and Epic.

Note

Querying epics is available only on the Premium and Ultimate tier.

Query fields

Field Name (and alias) Operators Types
Assignees assignee, assignees =, in, != All
Author author =, in, != All
Cadence cadence =, in All except Epic
Closed at closed, closedAt =, >, <, >=, <= All
Confidential confidential =, != All
Created at created, createdAt, opened, openedAt =, >, <, >=, <= All
Custom field customField("Field name") = All
Due date due, dueDate =, >, <, >=, <= All
Epic epic =, != All except Epic
Group group = All
Health status health, healthStatus =, != All
ID id =, in All
Include subgroups includeSubgroups =, != All
Iteration iteration =, in, != All except Epic
Labels label, labels =, in, != All
Milestone milestone =, in, != All
My reaction emoji myReaction, myReactionEmoji =, != All
Parent parent =, != All except Epic
Project project = All except Epic
State state = All
Status status = All except Epic
Subscribed subscribed =, != All
Updated at updated, updatedAt =, >, <, >=, <= All
Weight weight =, != All except Epic

Assignees {#workitem-assignees}

Version history

  • Alias assignees introduced in GitLab 18.0.
  • Support for querying epics by assignees introduced in GitLab 18.3.

Description: Query work items by one or more users who are assigned to them.

Allowed value types:

  • String
  • User (for example, @username)
  • List (containing String or User values)
  • Nullable (either of null, none, or any)

Author {#workitem-author}

Version history

  • Support for querying epics by author introduced in GitLab 18.1.
  • Support for in operator introduced in GitLab 18.3.

Description: Query work items by their author.

Allowed value types:

  • String
  • User (for example, @username)
  • List (containing String or User values)

Cadence {#workitem-cadence}

Version history

Description: Query work items except epics by the cadence that the work item's iteration is a part of.

Allowed value types:

  • Number (only positive integers)
  • List (containing Number values)
  • Nullable (either of none, or any)

Notes:

  • Because a work item can have only one iteration, the = operator cannot be used with List type for the cadence field.

Closed at {#workitem-closed-at}

Version history

  • Alias closedAt introduced in GitLab 18.0.
  • Operators >= and <= introduced in GitLab 18.0.
  • Support for querying epics by closed date introduced in GitLab 18.3.

Description: Query work items by the date when they were closed.

Allowed value types:

  • AbsoluteDate (in the format YYYY-MM-DD)
  • RelativeDate (in the format <sign><digit><unit>, where sign is +, -, or omitted, digit is an integer, and unit is one of d (days), w (weeks), m (months) or y (years))

Notes:

  • For the = operator, the time range is considered from 00:00 to 23:59 in the user's time zone.
  • >= and <= operators are inclusive of the dates being queried, whereas > and < are not.

Confidential {#workitem-confidential}

Version history

  • Support for querying epics by their confidentiality introduced in GitLab 18.1.

Description: Query work items by their visibility to project members.

Allowed value types:

  • Boolean (either of true or false)

Notes:

  • Confidential work items queried using GLQL are only visible to people who have permission to view them.

Created at {#workitem-created-at}

Version history

  • Aliases createdAt, opened, and openedAt introduced in GitLab 18.0.
  • Operators >= and <= introduced in GitLab 18.0.
  • Support for querying epics by creation date introduced in GitLab 18.1.

Description: Query work items by the date when they were created.

Allowed value types:

  • AbsoluteDate (in the format YYYY-MM-DD)
  • RelativeDate (in the format <sign><digit><unit>, where sign is +, -, or omitted, digit is an integer, and unit is one of d (days), w (weeks), m (months) or y (years))

Notes:

  • For the = operator, the time range is considered from 00:00 to 23:59 in the user's time zone.
  • >= and <= operators are inclusive of the dates being queried, whereas > and < are not.

Custom field {#workitem-custom-field}

  • Tier: Premium, Ultimate

Version history

Description: Query work items by custom fields.

Allowed value types:

  • String (for single-select custom fields)
  • List (of String, for multi-select custom fields)

Notes:

  • Custom field names and values are not case-sensitive.

Due date {#workitem-due-date}

Version history

  • Alias dueDate introduced in GitLab 18.0.
  • Operators >= and <= introduced in GitLab 18.0.
  • Support for querying epics by due date introduced in GitLab 18.3.

Description: Query work items by the date when they are due.

Allowed value types:

  • AbsoluteDate (in the format YYYY-MM-DD)
  • RelativeDate (in the format <sign><digit><unit>, where sign is +, -, or omitted, digit is an integer, and unit is one of d (days), w (weeks), m (months) or y (years))

Notes:

  • For the = operator, the time range is considered from 00:00 to 23:59 in the user's time zone.
  • >= and <= operators are inclusive of the dates being queried, whereas > and < are not.

Epic {#workitem-epic}

  • Tier: Premium, Ultimate

Version history

Description: Query work items by their parent epic ID or reference.

Allowed value types:

  • Number (epic ID)
  • String (containing an epic reference like &123)
  • Epic (for example, &123, gitlab-org&123)

Group {#workitem-group}

Description: Query work items in all projects in a given group.

Allowed value types: String

Notes:

  • Only one group can be queried at a time.
  • The group cannot be used together with the project field.
  • If omitted when using inside an embedded view in a group object (like an epic), group is assumed to be the current group.
  • Using the group field queries all objects in that group, all its subgroups, and child projects.
  • By default, work items are searched in all descendant projects across all subgroups. To query only the direct child projects of the group, set the includeSubgroups field to false.

Health status {#workitem-health-status}

  • Tier: Ultimate

Version history

  • Alias healthStatus introduced in GitLab 18.0.
  • Support for querying epics by health status introduced in GitLab 18.3.

Description: Query work items by their health status.

Allowed value types:

  • StringEnum (one of "needs attention", "at risk" or "on track")
  • Nullable (either of null, none, or any)

ID {#workitem-identifier}

Version history

Description: Query work items by their IDs.

Allowed value types:

  • Number (only positive integers)
  • List (containing Number values)

Include subgroups {#workitem-include-subgroups}

Version history

  • Introduced in GitLab 17.10.
  • Support for this field to be used with epics introduced in GitLab 18.1.

Description: Query work items in the entire hierarchy of a group.

Allowed value types:

  • Boolean (either of true or false)

Notes:

  • This field can only be used with the group field.
  • The value of this field defaults to false.

Iteration {#workitem-iteration}

  • Tier: Premium, Ultimate

Version history

Description: Query work items, except epics, by their associated iteration.

Allowed value types:

  • Number (only positive integers)
  • Iteration (for example, *iteration:123456)
  • List (containing Number or Iteration values)
  • Enum (only current is supported)
  • Nullable (either of none, or any)

Notes:

  • Because a work item can have only one iteration, the = operator cannot be used with List type for the iteration field.

Labels {#workitem-labels}

Version history

  • Support for label value types introduced in GitLab 17.8.
  • Alias labels introduced in GitLab 18.0.
  • Support for querying epics by labels introduced in GitLab 18.1.

Description: Query work items by their associated labels.

Allowed value types:

  • String
  • Label (for example, ~bug, ~"team::planning")
  • List (containing String or Label values)
  • Nullable (either of none, or any)

Notes:

  • Scoped labels, or labels containing spaces must be wrapped in quotes.

Milestone {#workitem-milestone}

Version history

  • Support for milestone value types introduced in GitLab 17.8.
  • Support for querying epics by milestone introduced in GitLab 18.1.

Description: Query work items by their associated milestone.

Allowed value types:

  • String
  • Milestone (for example, %Backlog, %"Awaiting Further Demand")
  • List (containing String or Milestone values)
  • Nullable (either of none, or any)

Notes:

  • Milestones containing spaces must be wrapped in quotes (").
  • Because a work item can have only one milestone, the = operator cannot be used with List type for the milestone field.
  • The Epic type does not support wildcard milestone filters like none or any.

My reaction emoji {#workitem-my-reaction-emoji}

Version history

Description: Query work items by the current user's emoji reaction on it.

Allowed value types: String

Parent {#workitem-parent}

Description: Query work items, except epics, by their parent work item or epic.

Allowed value types:

  • Number (parent ID)
  • String (containing a reference like #123)
  • WorkItem (for example, #123, gitlab-org/gitlab#123)
  • Epic (for example, &123, gitlab-org&123)

Project {#workitem-project}

Description: Query work items, except epics, in a particular project.

Allowed value types: String

Notes:

  • Only one project can be queried at a time.
  • The project field cannot be used together with the group field.
  • If omitted when using inside an embedded view, project is assumed to be the current project.

State {#workitem-state}

Version history

Description: Query work items by state.

Allowed value types:

  • Enum, one of opened, closed, or all

Notes:

  • The state field does not support the != operator.

Status {#workitem-status}

  • Tier: Premium, Ultimate

Version history

Description: Query work items by their status.

Allowed value types: String

Subscribed {#workitem-subscribed}

Version history

Description: Query work items by whether the current user has set notifications on or off.

Allowed value types: Boolean

Updated at {#workitem-updated-at}

Version history

  • Alias updatedAt introduced in GitLab 18.0.
  • Operators >= and <= introduced in GitLab 18.0.
  • Support for querying epics by last updated introduced in GitLab 18.1.

Description: Query work items by when they were last updated.

Allowed value types:

  • AbsoluteDate (in the format YYYY-MM-DD)
  • RelativeDate (in the format <sign><digit><unit>, where sign is +, -, or omitted, digit is an integer, and unit is one of d (days), w (weeks), m (months) or y (years))

Notes:

  • For the = operator, the time range is considered from 00:00 to 23:59 in the user's time zone.
  • >= and <= operators are inclusive of the dates being queried, whereas > and < are not.

Weight {#workitem-weight}

  • Tier: Premium, Ultimate

Description: Query work items, except epics, by their weight.

Allowed value types:

  • Number (only positive integers or 0)
  • Nullable (either of null, none, or any)

Notes:

  • Comparison operators < and > cannot be used.

Display fields

Version history

Field Name or alias Types Description
Assignees assignee, assignees All Display users assigned to the object
Author author All Display the author of the object
Closed at closed, closedAt All Display time since the object was closed
Confidential confidential All Display Yes or No indicating whether the object is confidential
Created at created, createdAt All Display time since the object was created
Description description All Display the description of the object
Due date due, dueDate All Display time until the object is due
Epic epic All except Epic Display a link to the epic. Available in the Premium and Ultimate tier
Health status health, healthStatus All Display a badge indicating the health status. Available in the Ultimate tier
ID id All Display the ID of the object
Iteration iteration All except Epic Display the iteration. Available in the Premium and Ultimate tier
Labels label, labels All Display labels. Can accept parameters to filter specific labels, for example labels("workflow::*", "backend")
Last comment lastComment All Display the last comment made on the object
Milestone milestone All Display the milestone associated with the object
Start date start, startDate Epic only Display the start date of the epic
State state All Display a badge indicating the state. Values are Open or Closed
Status status All except Epic Display a badge indicating the status. For example, "To do" or "Complete". Available in the Premium and Ultimate tiers
Subscribed subscribed All Display Yes or No indicating whether the current user is subscribed
Title title All Display the title of the object
Type type All Display the work item type, for example Issue, Task, or Objective
Updated at updated, updatedAt All Display time since the object was last updated
Weight weight All except Epic Display the weight. Available in the Premium and Ultimate tiers

Sort fields

Version history

Field Name (and alias) Types Description
Closed at closed, closedAt All Sort by closed date
Created created, createdAt All Sort by created date
Due date due, dueDate All Sort by due date
Health status health, healthStatus All Sort by health status
Milestone milestone All except Epic Sort by milestone due date
Popularity popularity All Sort by the number of thumbs up emoji reactions
Start date start, startDate Epic only Sort by start date
Title title All Sort by title
Updated at updated, updatedAt All Sort by last updated date
Weight weight All except Epic Sort by weight

Examples:

  • List all issues in the gitlab-org/gitlab project sorted by title:

    ```glql
display: table
fields: state, title, updated
sort: title asc
query: project = "gitlab-org/gitlab" and type = Issue
```

  • List all epics in the gitlab-org group sorted by the start date (oldest first):

    ```glql
display: table
fields: title, state, startDate
sort: startDate asc
query: group = "gitlab-org" and type = Epic
```

  • List all issues in the gitlab-org group with an assigned weight sorted by the weight (highest first):

    ```glql
display: table
fields: title, weight, health
sort: weight desc
query: type = Issue and group = "gitlab-org" and weight = any
```

  • List all issues in the gitlab-org group due up to a week from today sorted by the due date (earliest first):

    ```glql
display: table
fields: title, dueDate, assignee
sort: dueDate asc
query: type = Issue and group = "gitlab-org" and due >= today() and due <= 1w
```