doc/user/tasks.md
{{< details >}}
{{< /details >}}
{{< history >}}
work_items. Disabled by default.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.
A task in GitLab is a planning item that can be created in an issue. Use tasks to break down user stories captured in issues into smaller, trackable items.
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.
For the latest updates, check the Tasks roadmap.
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 in issues, in the Child items section.
You can also filter the list of work items
for Type = task.
When you select a task from an issue or from the Work items list, it opens in a details panel on the right side of the screen. On smaller screens, this panel overlaps the page.
To open a task in full-page view:
{{< history >}}
{{< /history >}}
Prerequisites:
To create a task:
{{< history >}}
{{< /history >}}
Prerequisites:
To convert a task list item in an issue description to a task:
The task list item is removed from the issue description and added to the Child items section. Any nested task list items are moved up a nested level.
{{< history >}}
{{< /history >}}
Prerequisites:
To add an existing task to an issue:
{{< history >}}
{{< /history >}}
Prerequisites:
To edit a task:
{{< history >}}
work_items_mvc. Disabled by default.work_items_mvc removed.{{< /history >}}
Use a rich text editor to edit a task's description.
Prerequisites:
To edit the description of a task:
{{< history >}}
{{< /history >}}
Prerequisites:
To promote a task to an issue:
In the top bar, select Search or go to and find your project.
Select Plan > Work items, then filter by Type = Task and select your task.
Unlink the parent issue and promote the task: In the task window, use these two quick actions in separate comments:
/remove_parent
/promote_to issue
The task is converted to an issue. The previous URL with /work_items/ still works.
{{< history >}}
work_items_beta. Disabled by default.okrs_mvc. For current flag state, see the top of this page.{{< /history >}}
Convert a task into another item type, such as:
[!warning] Changing the type might result in data loss if the target type does not support all fields from the original type.
Prerequisites:
To convert a task into another item type:
/remove_parent quick action.Alternatively, you can use the /type quick action, followed
by issue, objective or key result in a comment.
{{< history >}}
{{< /history >}}
Prerequisites:
You can remove a task from an issue without deleting it. To reconnect them, see Set an issue as a parent.
To remove a task from an issue using the Child items section:
To remove a task from an issue using the task details panel:
{{< history >}}
{{< /history >}}
Prerequisites:
To delete a task:
{{< history >}}
{{< /history >}}
Prerequisites:
By default, tasks are ordered by creation date. To reorder them in an issue's Child items section, drag them into the desired order.
To sort tasks in the Work items list:
On the right of the filter bar, select the Created date dropdown list.
Select a sort criteria:
To toggle between ascending and descending order, select Sort direction ({{< icon name="sort-lowest" >}} or {{< icon name="sort-highest" >}}).
{{< details >}}
{{< /details >}}
{{< history >}}
work_item_status_feature_flag. Enabled by default.work_item_status_feature_flag removed.{{< /history >}}
<!-- Turn off the future tense test because of "won't do". --> <!-- vale gitlab_base.FutureTense = NO -->You can assign a status to tasks to track their progress through your workflow. Status provides more granular tracking than the basic open/closed states, allowing you to use specific stages like In progress, Done, or Won't do.
<!-- vale gitlab_base.FutureTense = YES -->For more information about status, including how to configure custom statuses, see Status.
Prerequisites:
To change the status of a task:
The task's status updates immediately.
You can also set the status by using the /status quick action.
{{< history >}}
{{< /history >}}
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:
To change the assignee on a task:
{{< history >}}
{{< /history >}}
Prerequisites:
To add labels to a task:
{{< history >}}
work_items_mvc_2. Disabled by default.work_items_mvc_2 removed.{{< /history >}}
You can set a start and due date on a task.
Prerequisites:
You can set start and due dates on a task to show when work should begin and end.
To set a start or due date:
{{< history >}}
work_items_mvc_2. Disabled by default.work_items_mvc in GitLab 15.7. Disabled by default.work_items_mvc removed.{{< /history >}}
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:
To add a task to a milestone:
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Prerequisites:
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:
{{< history >}}
use_cached_rolled_up_weights. Disabled by default.use_cached_rolled_up_weights removed.{{< /history >}}
The number of descendant tasks and their total weight is displayed in the issue description, in the Child items section header.
To see the number of open and closed tasks:
The numbers reflect all child tasks associated with the issue, including those you might not have permission to view.
{{< history >}}
use_cached_rolled_up_weights. Disabled by default.use_cached_rolled_up_weights removed.{{< /history >}}
The issue progress percentage is displayed in the issue description, in the Child items section header.
To see the completed and total weight of child tasks:
The weights and progress reflect all tasks associated with the issue, including those you might not have permission to view.
{{< details >}}
{{< /details >}}
{{< history >}}
work_items_mvc_2. Disabled by default.work_items_mvc in GitLab 15.7. Disabled by default.work_items_mvc removed.{{< /history >}}
You can add a task to an iteration. You can see the iteration title and period only when you view a task.
Prerequisites:
To add a task to an iteration:
{{< history >}}
{{< /history >}}
You can estimate and track the time you spend on a task.
For more information, see Time tracking.
{{< history >}}
{{< /history >}}
If a task description is long, GitLab displays only part of it. To see the whole description, you must select Read more. This truncation makes it easier to find other elements on the page without scrolling through lengthy text.
To change whether descriptions are truncated:
This setting is remembered and affects all issues, tasks, epics, objectives, and key results.
{{< history >}}
{{< /history >}}
Task attributes are shown in a sidebar to the right of the description when space allows. To hide the sidebar and increase space for the description:
This setting is remembered and affects all issues, tasks, epics, objectives, and key results.
To show the sidebar again:
{{< history >}}
work_items_mvc_2. Disabled by default.work_items_mvc in GitLab 15.8. Disabled by default.work_items_mvc removed.{{< /history >}}
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.
You can add comments and reply to threads in tasks.
{{< history >}}
{{< /history >}}
To refer to a task elsewhere in GitLab, you can use its full URL or a short reference like
namespace/project-name#123, where namespace is a group or username.
To copy the task reference to your clipboard:
You can now paste the reference into another description or comment.
For more information about task references, see GitLab-Flavored Markdown.
{{< history >}}
{{< /history >}}
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:
{{< history >}}
{{< /history >}}
Prerequisites:
To set an issue as a parent of a task:
To remove the parent item of the task:
Participants are users who interacted with a task. For information about viewing participants, see participants.
{{< history >}}
{{< /history >}}
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.
By default, tasks are public. You can make a task confidential when you create or edit it.
Prerequisites:
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.
To change the confidentiality of an existing task:
When a task is made confidential, only users with the Reporter, Developer, Maintainer, or Owner role for the project can access it. Users with the Guest or Minimal role can't access the task even if they were previously participating in it.
A user with the Guest role can create confidential tasks but can only view the ones they created.
Users with the Guest role or non-members can view a confidential task if they are assigned to it. 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 tasks are visually different from regular tasks in a few ways. Wherever tasks are listed, you can see the confidential ({{< icon name="eye-slash" >}}) 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 name="eye-slash" >}}) 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:
{{< history >}}
work_items_beta. Disabled by default.work_items_beta removed in GitLab 18.6.{{< /history >}}
You can prevent public comments in a task. When you do, only project members can add and edit comments.
Prerequisites:
To lock a task:
A system note is added to the page details.
If a task is closed with a locked discussion, then you cannot reopen it until the discussion is unlocked.
{{< history >}}
linked_work_items. Disabled by default.linked_work_items removed.{{< /history >}}
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.
Prerequisites:
To link an item to a task:
When you have finished adding all linked items, you can see them categorized so their relationships can be better understood visually.
Prerequisites:
Due to the bi-directional relationship, the relationship no longer appears in either item.
{{< history >}}
{{< /history >}}
You can set a task to close when a merge request merges.
Prerequisites:
The merge requests are now visible in the main body, in the Development section.
Use the exact closing pattern to add the merge request to the task.
If automatic issue closing is enabled in your project settings, the task is automatically closed when either: