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.

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

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

Description: Query work items by their author.

Allowed value types:

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

Cadence

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

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

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

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

Tier: Premium, Ultimate

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

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

Tier: Premium, Ultimate

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

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

Tier: Ultimate

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

Description: Query work items by their IDs.

Allowed value types:

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

Include subgroups

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

Tier: Premium, Ultimate

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

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

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

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

Allowed value types: String

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

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

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

Tier: Premium, Ultimate

Description: Query work items by their status.

Allowed value types: String

Subscribed

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

Allowed value types: Boolean

Updated at

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

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

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

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
```