doc/user/project/issues/managing_issues.md
{{< details >}}
{{< /details >}}
GitLab issues help you track work and collaborate with your team. You can manage issues to:
For information on managing child items of an issue, see child items.
{{< history >}}
{{< /history >}}
You can edit an issue's title and description.
Prerequisites:
To edit an issue:
{{< details >}}
{{< /details >}}
{{< collapsible title="Model information" >}}
{{< /collapsible >}}
{{< history >}}
{{< /history >}}
Generate a detailed description for an issue based on a short summary you provide.
<i class="fa-youtube-play" aria-hidden="true"></i> Watch an overview
<!-- Video published on 2024-12-18 -->Prerequisites:
To generate an issue description:
The issue description is replaced with AI-generated text.
Provide feedback on this experimental feature in issue 409844.
Data usage: When you use this feature, the text you enter is sent to the large language model.
{{< history >}}
{{< /history >}}
You can edit multiple issues at a time when you're in a group or project.
Prerequisites:
To edit multiple issues at the same time:
When bulk editing issues, you can edit the following attributes:
{{< history >}}
{{< /history >}}
When you move an issue, it's closed and copied to the target project. The original issue is not deleted. A system note, which indicates where it came from and went to, is added to both issues.
Be careful when moving an issue to a project with different access rules. Before moving the issue, make sure it does not contain sensitive data.
Prerequisites:
To move an issue:
You can also use the /move quick action in a comment or description.
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
{{< history >}}
{{< /history >}}
You can move multiple issues at the same time when you're in a project. You can't move tasks or test cases.
Prerequisites:
To move multiple issues at the same time:
You can move all open issues from one project to another.
Prerequisites:
To do it:
Optional (but recommended). Create a backup before attempting any changes in the console.
Open the Rails console.
Run the following script. Make sure to change project, admin_user, and target_project to
your values.
project = Project.find_by_full_path('full path of the project where issues are moved from')
issues = project.issues
admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues
target_project = Project.find_by_full_path('full path of target project where issues moved to')
issues.each do |issue|
if issue.state != "closed" && issue.moved_to.nil?
Issues::MoveService.new(container: project, current_user: admin_user).execute(issue, target_project)
else
puts "issue with id: #{issue.id} and title: #{issue.title} was not moved"
end
end; nil
To exit the Rails console, enter quit.
When you use ordered lists, unordered lists, or task lists in issue descriptions, you can:
Prerequisites:
In an issue description with task list items:
The task list item is removed from the issue description. Any nested task list items are moved up a nested level.
{{< history >}}
{{< /history >}}
When you view an issue that has a list in the description, you can also reorder the list items.
Prerequisites:
To reorder list items, when viewing an issue:
{{< history >}}
{{< /history >}}
When you decide that an issue is resolved or no longer needed, you can close it. The issue is marked as closed but is not deleted.
Prerequisites:
To close an issue, you can either:
You can also use the /close quick action in a comment or description.
{{< history >}}
{{< /history >}}
Prerequisites:
To reopen a closed issue, in the upper-right corner, select More actions ({{< icon name="ellipsis_v" >}}) and then Reopen issue. A reopened issue is no different from any other open issue.
You can also use the /reopen quick action in a comment or description.
You can close issues automatically by using certain words, called a closing pattern, in a commit message or merge request description. GitLab Self-Managed administrators can change the default closing pattern.
If a commit message or merge request description contains text matching the closing pattern, all issues referenced in the matched text are closed when either:
For example, if you include Closes #4, #6, Related to #5 in a merge request
description:
#4 and #6 are closed automatically when the MR is merged.#5 is marked as a related issue, but it's not closed automatically.Alternatively, when you create a merge request from an issue, it inherits the issue's milestone and labels.
For performance reasons, automatic issue closing is disabled for the very first push from an existing repository.
When you merge a merge request, it's your responsibility to check that it's appropriate for any targeted issues to close. Users can include issue closing patterns in the merge request description, and also in the body of a commit message. Closing messages in commit messages are easy to miss. In both cases, the merge request widget shows information about the issue to close on merge:
When you merge a merge request, GitLab checks that you have permission to close the targeted issues. In public repositories, this check is important, because external users can create both merge requests and commits that contain closing patterns. When you are the user who merges, it's important that you are aware of the effects the merge has on both the code and issues in your project.
When auto-merge is enabled for a merge request, no further changes can be made to the list of issues that will be automatically closed.
{{< history >}}
{{< /history >}}
To automatically close an issue, use the following keywords followed by the issue reference.
Available keywords:
Close, Closes, Closed, Closing, close, closes, closed, closingFix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixingResolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolvingImplement, Implements, Implemented, Implementing, implement, implements, implemented, implementingAvailable issue reference formats:
#123).group/project#123).https://gitlab.example.com/<project_full_path>/-/issues/123).https://gitlab.example.com/<project_full_path>/-/work_items/123).https://gitlab.example.com/groups/<group_full_path>/-/work_items/123).For example:
Awesome commit message
Fix #20, Fixes #21 and Closes group/otherproject#22.
This commit is also related to #17 and fixes #18, #19
and https://gitlab.example.com/group/otherproject/-/issues/23.
The previous commit message closes #18, #19, #20, and #21 in the project this commit is pushed to,
as well as #22 and #23 in group/otherproject. #17 is not closed as it does
not match the pattern.
You can use the closing patterns in multi-line commit messages or one-liners
done from the command line with git commit -m.
The default issue closing pattern regex:
\b((?:[Cc]los(?:e[sd]?|ing)|\b[Ff]ix(?:e[sd]|ing)?|\b[Rr]esolv(?:e[sd]?|ing)|\b[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?: *,? +and +| *,? *)?)|([A-Z][A-Z0-9_]+-\d+))+)
{{< history >}}
{{< /history >}}
You can disable the automatic issue closing feature on a per-project basis in the project's settings.
Prerequisites:
To disable automatic issue closing:
Referenced issues are still displayed, but are not closed automatically.
Changing this setting applies only to new merge requests or commits. Already closed issues remain as they are. Disabling automatic issue closing only applies to issues in the project where the setting was disabled. Merge requests and commits in this project can still close another project's issues.
{{< details >}}
{{< /details >}}
Prerequisites:
Learn how to change the default issue closing pattern of your installation.
{{< history >}}
{{< /history >}}
If an issue 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 >}}
Issue 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 >}}
{{< /history >}}
Prerequisites:
To delete an issue:
{{< history >}}
{{< /history >}}
Prerequisites:
To change issue type:
In the top bar, select Search or go to and find your project.
Select Plan > Work items, then filter by Type = Issue and select your issue.
In the upper-right corner, select More actions ({{< icon name="ellipsis_v" >}}).
Select Change type.
From the Type dropdown list select the new type:
Select Change type.
To promote an issue to an incident, see promote an issue to an incident
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
You can promote an issue to an epic in the immediate parent group.
Promoting a confidential issue to an epic creates a confidential epic, retaining confidentiality.
When an issue is promoted to an epic:
The following issue metadata is copied to the epic:
Prerequisites:
To promote an issue to an epic:
Alternatively, you can use the /promote_to Epic quick action.
You can use the /promote_to Incident quick action to promote the issue to an incident.
{{< details >}}
{{< /details >}}
To add an issue to an iteration:
To add an issue to an iteration, you can also:
/iteration quick action.To view all issues assigned to you:
Or:
The issue list shows all issues in your project or group. You can use it to view, sort, and manage issues.
To view the issue list:
To set which attributes are shown in the Work items list, configure display preferences.
From the issue list, you can:
The following sections describe how to work with the issue list.
{{< history >}}
or_issuable_queries. Disabled by default.or_issuable_queries removed.{{< /history >}}
To filter the list of issues:
=: Is!=: Is not one of||: Is one of (for Assignee, Author, Label, Type).
Works like an inclusive OR.
For example, if you filter by Assignee is one of Sidney Jones and Assignee is one of Zhang Wei,
GitLab shows issues where either Sidney, Zhang, or both of them are assignees.AND.To filter the list issues for text in a title or description:
Filtering issues uses PostgreSQL full text search to match meaningful and significant words to answer a query.
For example, if you search for I am securing information for M&A,
GitLab can return results with securing, secured,
or information in the title or description.
However, GitLab doesn't match the sentence or the words I, am or M&A exactly,
as they aren't deemed lexically meaningful or significant.
It's a limitation of PostgreSQL full text search.
# followed by the issue ID.
For example, enter #362255 to return only issue 362255.{{< history >}}
issues_list_drawer. Disabled by default.issues_list_drawer removed.{{< /history >}}
When you select an issue from the list or issue board, it opens in a details panel.
You can then view and edit its details without losing context of the list or board.
When using the panel:
To open the issue in full view:
my_project#123.To always open issues in full page view, configure your list display preferences.
To refer to an issue 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 issue reference to your clipboard:
You can now paste the reference into another description or comment.
For more information, see GitLab-specific references.
You can create a comment in an issue 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 issue's email address:
An issue can be assigned to one or more users.
The assignees can be changed as often as needed. The idea is that the assignees are people responsible for the issue. When an issue is assigned to someone, it appears in their Assigned work items page.
If a user is not a member of a project, an issue can only be assigned to them if they create it themselves or another project member assigns them.
{{< history >}}
{{< /history >}}
Prerequisites:
To change the assignee on an issue:
The assignee is changed without having to refresh the page.
To prevent duplication of issues on the same topic, GitLab searches for similar issues when you create a new issue.
As you type in the title text box of the New issue page, GitLab searches titles and descriptions across all issues in the current project. Only issues you have access to are returned. Up to five similar issues, sorted by most recently updated, are displayed below the title text box.
{{< details >}}
{{< /details >}}
To better track the risk in meeting your plans, you can assign a health status to each issue. You can use health status to signal to others in your organization whether issues are progressing as planned or need attention to stay on schedule.
Incorporate a review of issue health status into your daily stand-up, project status reports, or weekly meetings to address risks to timely delivery of your planned work.
{{< history >}}
{{< /history >}}
Prerequisites:
To edit health status of an issue:
In the top bar, select Search or go to and find your project.
Select Plan > Work items, then filter by Type = Issue and select your issue.
In the right sidebar, in the Health status section, select Edit.
From the dropdown list, select the status to add to this issue:
You can see the issue's health status in:
After an issue is closed, its health status can't be edited and the Edit button becomes disabled until the issue is reopened.
You can also set and clear health statuses using the /health_status and /clear_health_status
quick actions.
{{< 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 issues to track their progress through your workflow. Status provides more granular tracking than the basic open/closed states, so you can use specific stages like In progress, Done, or Won't do.
For more information about how to configure custom statuses, see the status section.
<!-- vale gitlab_base.FutureTense = YES -->Prerequisites:
To change the status of an issue:
The issue's status updates immediately.
You can view the issue's status in:
You can also set the status by using the /status quick action.
Participants are users who interacted with an issue. For information about viewing participants, see participants.
{{< details >}}
{{< /details >}}
If a status page application is associated with the project, you can use the /publish quick action to publish the issue.
For more information, see GitLab Status Page.
You can also use quick actions to manage issues.
Some actions don't have corresponding UI buttons yet. You can do the following only by using quick actions:
/zoom and /remove_zoom)./publish)./clone)./duplicate)./copy_metadata).