- View tasks
- Create a task
- Add existing tasks to an issue
- Edit a task
- Promote a task to an issue
- Remove a task from an issue
- Delete a task
- Reorder tasks
- Assign users to a task
- Assign labels to a task
- Set a start and due date
- Add a task to a milestone
- Set task weight
- Add a task to an iteration
- View task system notes
- Comments and threads
- Copy task reference
- Copy task email address
- Confidential tasks
- Two-column layout
- Linked items in Tasks
Tasks
-
Introduced in GitLab 14.5 with a flag named
work_items
. Disabled by default. - Creating, editing, and deleting tasks introduced in GitLab 15.0.
- Enabled on GitLab.com and self-managed in GitLab 15.3.
Known limitation:
For the latest updates, check the Tasks Roadmap.
work_items
.
On GitLab.com, this feature is available.Use tasks to track steps needed for the issue to be closed.
When planning an issue, you need a way to capture and break down technical requirements or steps necessary to complete it. An issue with related tasks is better defined, and so you can provide a more accurate issue weight and completion criteria.
Tasks are a type of work item, a step towards default issue types in GitLab. For the roadmap of migrating issues and epics to work items and adding custom work item types, see epic 6033 or the Plan direction page.
View tasks
View tasks in issues, in the Tasks section.
You can also filter the list of issues
for Type = task
.
If you select a task from an issue, it opens in a dialog window. If you select a task to open in a new browser tab, or select it from the issue list, the task opens in a full-page view.
Create a task
Prerequisites:
- You must have at least the Reporter role for the project, or the project must be public.
To create a task:
- In the issue description, in the Tasks section, select Add.
- Select New task.
- Enter the task title.
- Select Create task.
From a task list item
Introduced in GitLab 15.9.
Prerequisites:
- You must have at least the Reporter role for the project.
In an issue description with task list items:
- Hover over a task list item and select the options menu ().
- Select Convert to task.
The task list item is removed from the issue description and a task is created in the tasks widget from its contents. Any nested task list items are moved up a nested level.
Add existing tasks to an issue
Introduced in GitLab 15.6.
Prerequisites:
- You must have at least the Guest role for the project, or the project must be public.
To add a task:
- In the issue description, in the Tasks section, select Add.
- Select Existing task.
- Search tasks by title.
- Select one or multiple tasks to add to the issue.
- Select Add task.
Edit a task
Prerequisites:
- You must have at least the Reporter role for the project.
To edit a task:
- In the issue description, in the Tasks section, select the task you want to edit. The task window opens.
- Optional. To edit the title, select it and make your changes.
- Optional. To edit the description, select the edit icon (), make your changes, and select Save.
- Select the close icon ().
Using the rich text editor
- Rich text editing in the dialog view introduced in GitLab 15.6 with a flag named
work_items_mvc
. Disabled by default. - Rich text editing in the full page view introduced in GitLab 15.7.
work_items_mvc
. On GitLab.com, this feature
is not available. The feature is not ready for production use.Use a rich text editor to edit a task’s description.
Prerequisites:
- You must have at least the Reporter role for the project.
To edit the description of a task:
- In the Tasks section, select the title of the task you want to edit. The task window opens.
- Next to Description, select the edit icon (). The description text box appears.
- Above the text box, select Rich text.
- Make your changes, and select Save.
Promote a task to an issue
Introduced in GitLab 16.1.
Prerequisites:
- You must have at least the Reporter role for the project.
To promote a task to an issue, use the /promote_to issue
quick action.
Remove a task from an issue
Prerequisites:
- You must have at least the Reporter role for the project.
You can remove a task from an issue. The task is not deleted, but the two are no longer connected. It’s not possible to connect them again.
To remove a task from an issue:
- In the issue description, in the Tasks section, next to the task you want to remove, select the options menu ().
- Select Remove task.
Delete a task
Prerequisites:
- You must either:
- Be the author of the task and have at least the Guest role for the project.
- Have the Owner role for the project.
To delete a task:
- In the issue description, in the Tasks section, select the task you want to edit.
- In the task window, in the options menu (), select Delete task.
- Select OK.
Reorder tasks
Introduced in GitLab 16.0.
Prerequisites:
- You must have at least the Reporter role for the project.
By default, tasks are ordered by creation date. To reorder them, drag them around.
Assign users to a task
Introduced in GitLab 15.4.
To show who is responsible for a task, you can assign users to it.
Users on GitLab Free can assign one user per task. Users on GitLab Premium and Ultimate can assign multiple users to a single task. See also multiple assignees for issues.
Prerequisites:
- You must have at least the Reporter role for the project.
To change the assignee on a task:
- In the issue description, in the Tasks section, select the title of the task you want to edit. The task window opens.
- Next to Assignees, select Add assignees.
- From the dropdown list, select the users to add as an assignee.
- Select any area outside the dropdown list.
Assign labels to a task
Introduced in GitLab 15.5.
Prerequisites:
- You must have at least the Reporter role for the project.
To add labels to a task:
- In the issue description, in the Tasks section, select the title of the task you want to edit. The task window opens.
- Next to Labels, select Add labels.
- From the dropdown list, select the labels to add.
- Select any area outside the dropdown list.
Set a start and due date
-
Introduced in GitLab 15.4 with a flag named
work_items_mvc_2
. Disabled by default. - Enabled on GitLab.com and self-managed in GitLab 15.5.
You can set a start and due date on a task.
Prerequisites:
- You must have at least the Reporter role for the project.
You can set start and due dates on a task to show when work should begin and end.
To set a due date:
- In the issue description, in the Tasks section, select the title of the task you want to edit. The task window opens.
- If the task already has a due date next to Due date, select it. Otherwise, select Add due date.
- In the date picker, select the desired due date.
To set a start date:
- In the issue description, in the Tasks section, select the title of the task you want to edit. The task window opens.
- If the task already has a start date next to Start date, select it. Otherwise, select Add start date.
-
In the date picker, select the desired due date.
The due date must be the same or later than the start date. If you select a start date to be later than the due date, the due date is then changed to the same day.
Add a task to a milestone
-
Introduced in GitLab 15.5 with a flag named
work_items_mvc_2
. Disabled by default. -
Moved to feature flag named
work_items_mvc
in GitLab 15.7. Disabled by default. - Enabled on GitLab.com and self-managed in GitLab 15.7.
You can add a task to a milestone. You can see the milestone title when you view a task. If you create a task for an issue that already belongs to a milestone, the new task inherits the milestone.
Prerequisites:
- You must have at least the Reporter role for the project.
To add a task to a milestone:
- In the issue description, in the Tasks section, select the title of the task you want to edit. The task window opens.
- Next to Milestone, select Add to milestone. If a task already belongs to a milestone, the dropdown list shows the current milestone.
- From the dropdown list, select the milestone to be associated with the task.
Set task weight
Introduced in GitLab 15.3.
Prerequisites:
- You must have at least the Reporter role for the project.
You can set weight on each task to show how much work it needs. This value is visible only when you view a task.
To set issue weight of a task:
- In the issue description, in the Tasks section, select the title of the task you want to edit. The task window opens.
- Next to Weight, enter a whole, positive number.
- Select the close icon ().
Add a task to an iteration
-
Introduced in GitLab 15.5 with a flag named
work_items_mvc_2
. Disabled by default. -
Moved to feature flag named
work_items_mvc
in GitLab 15.7. Disabled by default. - Enabled on GitLab.com and self-managed in GitLab 15.7.
work_items_mvc
.
On GitLab.com, this feature is available.You can add a task to an iteration. You can see the iteration title and period only when you view a task.
Prerequisites:
- You must have at least the Reporter role for the project.
To add a task to an iteration:
- In the issue description, in the Tasks section, select the title of the task you want to edit. The task window opens.
- Next to Iteration, select Add to iteration.
- From the dropdown list, select the iteration to be associated with the task.
View task system notes
-
Introduced in GitLab 15.7 with a flag named
work_items_mvc_2
. Disabled by default. -
Moved to feature flag named
work_items_mvc
in GitLab 15.8. Disabled by default. - Changing activity sort order introduced in GitLab 15.8.
- Filtering activity introduced in GitLab 15.10.
- Enabled on GitLab.com and self-managed in GitLab 15.10.
You can view all the system notes related to the task. By default they are sorted by Oldest first. You can always change the sorting order to Newest first, which is remembered across sessions. You can also filter activity by Comments only and History only in addition to the default All activity which is remembered across sessions.
Comments and threads
You can add comments and reply to threads in tasks.
Copy task reference
Introduced in GitLab 16.1.
To refer to a task elsewhere in GitLab, you can use its full URL or a short reference, which looks like
namespace/project-name#123
, where namespace
is either a group or a username.
To copy the task reference to your clipboard:
- On the left sidebar, select Search or go to and find your project.
- Select Plan > Issues, then select your task to view it.
- In the top right corner, select the vertical ellipsis (), then select Copy Reference.
You can now paste the reference into another description or comment.
For more information about task references, see GitLab-Flavored Markdown.
Copy task email address
Introduced in GitLab 16.1.
You can create a comment in a task by sending an email. Sending an email to this address creates a comment that contains the email body.
For more information about creating comments by sending an email and the necessary configuration, see Reply to a comment by sending email.
To copy the task’s email address:
- On the left sidebar, select Search or go to and find your project.
- Select Plan > Issues, then select your issue to view it.
- In the top right corner, select the vertical ellipsis (), then select Copy task email address.
Confidential tasks
Introduced in GitLab 15.3.
Confidential tasks are tasks visible only to members of a project with sufficient permissions. You can use confidential tasks to keep security vulnerabilities private or prevent surprises from leaking out.
Make a task confidential
By default, tasks are public. You can make a task confidential when you create or edit it.
Prerequisites:
- You must have at least the Reporter role for the project.
- If the task has a parent issue which is non-confidential, and you want to make the issue confidential, you must first make all the child tasks confidential. A confidential issue can have only confidential children.
In a new task
When you create a new task, a checkbox right below the text area is available to mark the task as confidential.
Check that box and select Create task.
In an existing task
To change the confidentiality of an existing task:
- Open the task.
- In the top right corner, select the vertical ellipsis ().
- Select Turn on confidentiality.
Who can see confidential tasks
When a task is made confidential, only users with at least the Reporter role for the project have access to the task. Users with Guest or Minimal roles can’t access the task even if they were actively participating before the change.
However, a user with the Guest role can create confidential tasks, but can only view the ones that they created themselves.
Users with the Guest role or non-members can read the confidential task if they are assigned to the task. When a Guest user or non-member is unassigned from a confidential task, they can no longer view it.
Confidential tasks are hidden in search results for users without the necessary permissions.
Confidential task indicators
Confidential tasks are visually different from regular tasks in a few ways. Wherever tasks are listed, you can see the confidential () icon next to the tasks that are marked as confidential.
If you don’t have enough permissions, you cannot see confidential tasks at all.
Likewise, while inside the task, you can see the confidential () icon right next to the breadcrumbs.
Every change from regular to confidential and vice versa, is indicated by a system note in the task’s comments, for example:
- Jo Garcia made the issue confidential 5 minutes ago
- Jo Garcia made the issue visible to everyone just now
Two-column layout
Introduced in GitLab 16.2 with a flag named work_items_mvc_2
. Disabled by default.
work_items_mvc_2
.
On GitLab.com, this feature is not available.
This feature is not ready for production use.When enabled, tasks use a two-column layout, similar to issues. The description and threads are on the left, and attributes, such as labels or assignees, on the right.
Linked items in Tasks
Introduced in GitLab 16.5 with a flag named linked_work_items
. Disabled by default.
linked_work_items
.
On GitLab.com, this feature is not available.
This feature is not ready for production use.Linked items are a bi-directional relationship and appear in a block below the emoji reactions section. You can link an objective, key result, or a task in the same project with each other.
The relationship only shows up in the UI if the user can see both items.
Add a linked item
Prerequisite:
- You must have at least the Guest role for the project.
To link an item to a task:
- In the Linked items section of a task, select the Add button.
- Select the relationship between the two items. Either:
- relates to
- blocks
- is blocked by
- Enter the search text of the item.
- When you have added all the items to be linked, select Add below the search box.
When you have finished adding all linked items, you can see them categorized so their relationships can be better understood visually.
Remove a linked item
Prerequisite:
- You must have at least the Guest role for the project.
In the Linked items section of a task, next to each item, select the vertical ellipsis () and then select Remove.
Due to the bi-directional relationship, the relationship no longer appears in either item.