Tasks

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

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:

• Open it in a new browser tab by right-clicking the task, or by holding Command or Control and selecting it.
• In the upper-right corner of the details panel, select Open in full page ( ).

Create a task

Prerequisites:

• You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for the project, or the project must be public.

To create a task:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items.
3. In the top-right corner, select New item.
4. From the Type dropdown list, select Task if it is not already selected.
5. Complete the following:
   • Enter the task title.
   • Enter a task description.
   • Optional. In the dialog sidebar, select a Parent project for the new task.
6. Select Create task.

From a task list item

Prerequisites:

• You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for the project.

To convert a task list item in an issue description to a task:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Issue and select your issue.
3. In the issue description, hover over the task list item and select the options menu ( ).
4. Select Convert to child item.
5. Optional. Edit the task title and add a description.
6. Select Create 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.

Add existing tasks to an issue

Prerequisites:

• You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for the project, or the project must be public.

To add an existing task to an issue:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Issue and select your issue.
3. In the issue description, in the Child items section, select Add ( ).
4. Select Existing task.
5. Search tasks by title.
6. Select one or multiple tasks to add to the issue.
7. Select Add task.

Edit a task

Prerequisites:

• You must have the Planner, Reporter, Developer, Maintainer, or Owner role for the project.

To edit a task:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the upper-right corner, select Edit.
4. Optional. To edit the title, type into the Title text box.
5. Optional. To edit the description, make your changes to the Description text box.
6. Select Save changes.
7. Select the close icon ( ).

Using the rich text editor

Use a rich text editor to edit a task’s description.

Prerequisites:

• You must have the Planner, Reporter, Developer, Maintainer, or Owner role for the project.

To edit the description of a task:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the upper-right corner, select Edit.
4. At the bottom of the Description text box, select Switch to rich text editing. If the control shows Switch to plain text editing, the text box is already in rich text mode.
5. Make your changes, and select Save.

Promote a task to an issue

Prerequisites:

• You must have the Planner, Reporter, Developer, Maintainer, or Owner role for the project.

To promote a task to an issue:

1. In the top bar, select Search or go to and find your project.

2. Select Plan > Work items, then filter by Type = Task and select your task.

3. 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.

Convert a task into another item type

Convert a task into another item type, such as:

• Issue
• Objective
• Key result

Prerequisites:

• The task you want to convert must not have a parent item assigned.

To convert a task into another item type:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. Optional. If the task has a parent issue assigned, remove it. Add a comment to the task with the /remove_parent quick action.
4. In the upper-right corner, select More actions ( ), then select Change type.
5. Select the desired item type.
6. If all conditions are met, select Change type.

Alternatively, you can use the /type quick action, followed by issue, objective or key result in a comment.

Remove a task from an issue

Prerequisites:

• You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for the project.

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:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Issue and select your issue.
3. In the issue description, in the Child items section, select the options menu ( ) next to the task you want to remove.
4. Select Remove task.

To remove a task from an issue using the task details panel:

1. Select Plan > Work items, then filter by Type = Task and select your task.
2. In the right sidebar, next to Parent, select Edit.
3. In the upper-right corner of the dropdown list, select Clear.

Delete a task

Prerequisites:

• You must either:
  • Be the author of the task and have the Guest, Reporter, Developer, or Maintainer role for the project.
  • Have the Planner or Owner role for the project.

To delete a task:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. Select More actions ( ).
4. Select Delete task.
5. In the confirmation dialog, select Delete task.

Reorder tasks

Prerequisites:

• You must have the Planner, Reporter, Developer, Maintainer, or Owner role for the project.

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:

1. On the right of the filter bar, select the Created date dropdown list.

2. Select a sort criteria:

   • Priority
   • Created date
   • Updated date
   • Closed date
   • Milestone due date
   • Due date
   • Popularity
   • Label priority
   • Manual (drag items into your preferred order; sort direction is ignored)
   • Title
   • Start date

3. To toggle between ascending and descending order, select Sort direction ( or ).

Change status

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.

For more information about status, including how to configure custom statuses, see Status.

Prerequisites:

• You must have the Planner, Reporter, Developer, Maintainer, or Owner role for the project, be the author of the task, or be assigned to the task.

To change the status of a task:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the right sidebar, in the Status section, select Edit.
4. From the dropdown list, select the status.

The task’s status updates immediately.

You can also set the status by using the /status quick action.

Assign users to a task

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 the Planner, Reporter, Developer, Maintainer, or Owner role for the project.

To change the assignee on a task:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the right sidebar, in the Assignee section, select Edit.
4. From the dropdown list, select the users to add as an assignee.
5. Select any area outside the dropdown list.

Assign labels to a task

Prerequisites:

• You must have the Planner, Reporter, Developer, Maintainer, or Owner role for the project.

To add labels to a task:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the right sidebar, in the Labels section, select Edit.
4. From the dropdown list, select the labels to add.
5. Select any area outside the dropdown list.

Set a start and due date

You can set a start and due date on a task.

Prerequisites:

• You must have the Planner, Reporter, Developer, Maintainer, or Owner 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 start or due date:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the right sidebar, in the Dates section, select Edit.
4. Optional. In the Start date picker, select a date.
5. Optional. In the Due date picker, select a date. The due date must be the same as or later than the start date.
6. Select Apply.

Add a task to a milestone

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 the Planner, Reporter, Developer, Maintainer, or Owner role for the project.

To add a task to a milestone:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the right sidebar, in the Milestone section, select Edit.
4. From the dropdown list, select the milestone. If a task already belongs to a milestone, the dropdown list shows the current milestone.
5. Select any area outside the dropdown list.

Set task weight

Prerequisites:

• You must have the Reporter, Developer, Maintainer, or Owner 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:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the right sidebar, in the Weight section, select Edit.
4. Enter a whole, positive number.
5. Select Apply or press Enter.

View count and weight of tasks in the parent issue

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:

• In the section header, hover over the total counts.

The numbers reflect all child tasks associated with the issue, including those you might not have permission to view.

View progress of the parent issue

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:

• In the section header, hover over the percentage.

The weights and progress reflect all tasks associated with the issue, including those you might not have permission to view.

Add a task to an iteration

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 the Reporter, Developer, Maintainer, or Owner role for the project.

To add a task to an iteration:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the right sidebar, in the Iteration section, select Edit.
4. From the dropdown list, select the iteration to be associated with the task.
5. Select any area outside the dropdown list.

Estimate and track spent time

You can estimate and track the time you spend on a task.

For more information, see Time tracking.

Prevent truncating descriptions with Read more

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:

1. On a task, in the upper-right corner, select More actions ( ).
2. Toggle Truncate descriptions according to your preference.

This setting is remembered and affects all issues, tasks, epics, objectives, and key results.

Hide the right sidebar

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:

1. On a task, in the upper-right corner, select More actions ( ).
2. Select Hide sidebar.

This setting is remembered and affects all issues, tasks, epics, objectives, and key results.

To show the sidebar again:

• Repeat the previous steps and select Show sidebar.

View task system notes

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

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:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the upper-right corner, select More actions ( ), 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

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:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the upper-right corner, select More actions ( ), then select Copy task email address.

Set an issue as a parent

Prerequisites:

• You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for the project.
• The issue and task must belong to the same project.

To set an issue as a parent of a task:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the right sidebar, in the Parent section, select Edit.
4. From the dropdown list, select the parent to add.
5. Select any area outside the dropdown list.

To remove the parent item of the task:

1. In the Parent section, select Edit.
2. In the upper-right corner of the dropdown list, select Clear.
3. Select any area outside the dropdown list.

Participants

Participants are users who interacted with a task. For information about viewing participants, see participants.

Confidential tasks

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 the Reporter, Developer, Maintainer, or Owner 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:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the upper-right corner, select the vertical ellipsis ( ).
4. Select Turn on confidentiality.

Who can see confidential tasks

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

Lock discussion

You can prevent public comments in a task. When you do, only project members can add and edit comments.

Prerequisites:

• You must have the Reporter, Developer, Maintainer, or Owner role.

To lock a task:

1. In the upper-right corner, select the vertical ellipsis ( ).
2. Select Lock discussion.

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.

Linked items in tasks

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

Prerequisites:

• You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for the project.

To link an item to a task:

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. In the Linked items section of a task, select Add ( ).
4. Select the relationship between the two items. Either:
   • relates to
   • blocks
   • is blocked by
5. Enter the search text of the item, URL, or its reference ID.
6. 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

Prerequisites:

• You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for the project.

1. In the top bar, select Search or go to and find your project.
2. Select Plan > Work items, then filter by Type = Task and select your task.
3. 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.

Add a merge request and automatically close tasks

You can set a task to close when a merge request merges.

Prerequisites:

• You must have the Developer, Maintainer, or Owner role for the project containing the merge request.
• You must have the Reporter, Developer, Maintainer, or Owner role for the project containing the task.

1. Edit your merge request.
2. In the Description box, find and add the task.
   • Use the closing pattern that you would for adding a merge request to an issue.
   • If your task is in the same project as your merge request, you can search for your task by typing # followed by the task’s ID or title.
   • If your task is in a different project, with a task open, copy the URL from the browser or copy the task’s reference by selecting the vertical ellipsis ( ) in the upper-right corner, then Copy Reference.

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:

• The added merge request is merged.
• A commit referencing a task with the closing pattern is committed to your project’s default branch.

Related topics

• Create a merge request from a task