• Edit an issue
  • Remove a task list item
• Bulk edit issues from a project
  • Bulk edit issues from a group
• Move an issue
  • Moving tasks when the parent issue is moved
  • Bulk move issues
    • From the Issues page
    • From the Rails console
• Reorder list items in the issue description
• Close an issue
  • Reopen a closed issue
  • Closing issues automatically
    • User responsibility when merging
    • Default closing pattern
    • Disable automatic issue closing
    • Customize the issue closing pattern
• Change the issue type
• Delete an issue
• Promote an issue to an epic
• Promote an issue to an incident
• Add an issue to an iteration
• View all issues assigned to you
• Filter the list of issues
  • Filter by title or description
  • Filter with the OR operator
  • Filter issues by ID
• Copy issue reference
• Copy issue email address
• Assignees
  • Change assignee on an issue
• Similar issues
• Health status
  • Change health status of an issue
• Publish an issue
• Issue-related quick actions

Manage issues

After you create an issue, you can start working with it.

Edit an issue

You can edit an issue’s title and description.

Prerequisites:

• You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue.

To edit an issue:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues, then select the title of your issue to view it.
3. To the right of the title, select Edit title and description ().
4. Edit the available fields.
5. Select Save changes.

Remove a task list item

Prerequisites:

• You must have at least the Reporter role for the project, or be the author or assignee of the issue.

In an issue description with task list items:

1. Hover over a task list item and select the options menu ().
2. Select Delete.

The task list item is removed from the issue description. Any nested task list items are moved up a nested level.

Bulk edit issues from a project

You can edit multiple issues at a time when you’re in a project.

Prerequisites:

• You must have at least the Reporter role for the project.

To edit multiple issues at the same time:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues.
3. Select Bulk edit. A sidebar on the right of your screen appears.
4. Select the checkboxes next to each issue you want to edit.
5. From the sidebar, edit the available fields.
6. Select Update selected.

When bulk editing issues in a project, you can edit the following attributes:

• Status (open or closed)
• Assignees
• Epic
• Milestone
• Labels
• Health status
• Notification subscription
• Iteration
• Confidentiality

Bulk edit issues from a group

You can edit multiple issues across multiple projects when you’re in a group.

Prerequisites:

• You must have at least the Reporter role for a group.

To edit multiple issues at the same time:

1. On the left sidebar, select Search or go to and find your group.
2. Select Plan > Issues.
3. Select Bulk edit. A sidebar on the right of your screen appears.
4. Select the checkboxes next to each issue you want to edit.
5. From the sidebar, edit the available fields.
6. Select Update selected.

When bulk editing issues in a group, you can edit the following attributes:

• Epic
• Milestone
• Iteration
• Labels
• Health status

Move an issue

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:

• You must have at least the Reporter role for the project.

To move an issue:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues, then select your issue to view it.
3. On the right sidebar, select Move issue.
4. Search for a project to move the issue to.
5. Select Move.

Moving tasks when the parent issue is moved

When you move an issue to another project, all its child tasks are also moved to the target project and remain associated as child tasks on the moved issue. Each task is moved the same way as the parent, that is, it’s closed in the original project and copied to the target project.

Bulk move issues

From the Issues page

You can move multiple issues at the same time when you’re in a project. You can’t move tasks or test cases.

Prerequisites:

• You must have at least the Reporter role for the project.

To move multiple issues at the same time:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues.
3. Select Bulk edit. A sidebar on the right of your screen appears.
4. Select the checkboxes next to each issue you want to move.
5. From the right sidebar, select Move selected.
6. From the dropdown list, select the destination project.
7. Select Move.

From the Rails console

You can move all open issues from one project to another.

Prerequisites:

• You must have access to the Rails console of the GitLab instance.

To do it:

1. Optional (but recommended). Create a backup before attempting any changes in the console.
2. Open the Rails console.

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

4. To exit the Rails console, enter quit.

Reorder list items in the issue description

When you view an issue that has a list in the description, you can also reorder the list items.

Prerequisites:

• You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue.
• The issue’s description must have an ordered, unordered, or task list.

To reorder list items, when viewing an issue:

1. Hover over the list item row to make the grip icon () visible.
2. Select and hold the grip icon.
3. Drag the row to the new position in the list.
4. Release the grip icon.

Close an issue

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:

• You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue.

To close an issue, you can either:

• In an issue board, drag an issue card from its list into the Closed list.
• From any other page in the GitLab UI:
  1. On the left sidebar, select Search or go to and find your project.
  2. Select Plan > Issues, then select your issue to view it.
  3. In the upper-right corner, select Issue actions () and then Close issue.

Reopen a closed issue

Prerequisites:

• You must have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue.

To reopen a closed issue, in the upper-right corner, select Issue actions () and then Reopen issue. A reopened issue is no different from any other open issue.

Closing issues automatically

You can close issues automatically by using certain words, called a closing pattern, in a commit message or merge request description. Administrators of self-managed GitLab instances 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:

• The commit is pushed to a project’s default branch.
• The commit or merge request is merged into the default branch.

For example, if you include Closes #4, #6, Related to #5 in a merge request description:

• Issues #4 and #6 are closed automatically when the MR is merged.
• Issue #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.

User responsibility when merging

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.

Default closing pattern

To automatically close an issue, use the following keywords followed by the issue reference.

Available keywords:

• Close, Closes, Closed, Closing, close, closes, closed, closing
• Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing
• Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving
• Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing

Available issue reference formats:

• A local issue (#123).
• A cross-project issue (group/project#123).
• The full URL of an issue (https://gitlab.example.com/<project_full_path>/-/issues/123).
• The full URL of a work item (for example, task, objective, or key result):
  • In a project (https://gitlab.example.com/<project_full_path>/-/work_items/123).
  • In a group (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+))+)

Disable automatic issue closing

You can disable the automatic issue closing feature on a per-project basis in the project’s settings.

Prerequisites:

• You must have at least the Maintainer role for the project.

To disable automatic issue closing:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Repository.
3. Expand Branch defaults.
4. Clear the Auto-close referenced issues on default branch checkbox.
5. Select Save changes.

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.

Customize the issue closing pattern

Prerequisites:

• You must have administrator access to your GitLab instance.

Learn how to change the default issue closing pattern of your installation.

Change the issue type

Prerequisites:

• You must be the issue author or have at least the Reporter role for the project, be the author of the issue, or be assigned to the issue.

To change issue type:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues, then select your issue to view it.
3. To the right of the title, select Edit title and description ().

4. Edit the issue and select an issue type from the Issue type dropdown list:

   • Issue
   • Incident
5. Select Save changes.

Delete an issue

Prerequisites:

• You must have the Owner role for a project.

To delete an issue:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues, then select your issue to view it.
3. In the upper-right corner, select Issue actions ().
4. Select Delete issue.

Alternatively:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues, then select the title of your issue to view it.
3. Select Edit title and description ().
4. Select Delete issue.

Promote an issue to an epic

You can promote an issue to an epic in the immediate parent group.

When an issue is promoted to an epic:

• If the issue was confidential, an additional warning is displayed first.
• An epic is created in the same group as the project of the issue.
• Subscribers of the issue are notified that the epic was created.

The following issue metadata is copied to the epic:

• Title, description, activity, and comment threads.
• Upvotes and downvotes.
• Participants.
• Group labels that the issue had.
• Parent epic.

Prerequisites:

• The project to which the issue belongs must be in a group.
• You must have at least the Reporter role the project’s immediate parent group.
• You must either:
  • Have at least the Reporter role for the project.
  • Be the author of the issue.
  • Be assigned to the issue.

To promote an issue to an epic:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues, then select your issue to view it.
3. In the upper-right corner, select Issue actions ().
4. Select Promote to epic.

Alternatively, you can use the /promote quick action.

Promote an issue to an incident

You can use the /promote_to_incident quick action to promote the issue to an incident.

Add an issue to an iteration

To add an issue to an iteration:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues, then select your issue to view it.
3. On the right sidebar, in the Iteration section, select Edit.
4. From the dropdown list, select the iteration to add this issue to.
5. Select any area outside the dropdown list.

Alternatively, you can use the /iteration quick action.

View all issues assigned to you

To view all issues assigned to you:

1. On the left sidebar, select Search or go to.
2. From the dropdown list, select Issues assigned to me.

Or:

• To use a keyboard shortcut, press Shift + i.
• On the left sidebar, at the top, select Assigned issues ().

Filter the list of issues

To filter the list of issues:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues.
3. Above the list of issues, select Search or filter results.
4. In the dropdown list that appears, select the attribute you want to filter by.
5. Select or type the operator to use for filtering the attribute. The following operators are available:
   • =: Is
   • !=: Is not one of
6. Enter the text to filter the attribute by. You can filter some attributes by None or Any.
7. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical AND.

Filter by title or description

To filter the list issues for text in a title or description:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues.
3. Above the list of issues, in the Search or filter results text box, enter the searched phrase.
4. In the dropdown list that appears, select Search for this text.
5. Select the text box again, and in the dropdown list that appears, select Search Within, and then either Titles or Descriptions.
6. Press Enter or select the search icon ().

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 won’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.

Filter with the OR operator

You can use the OR operator (is one of: ||) when you filter the list of issues by:

• Assignees
• Author
• Labels

is one of represents 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.

Filter issues by ID

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues.
3. In the Search box, type the issue ID. For example, enter filter #10 to return only issue 10.

Copy issue reference

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:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues, then select your issue to view it.
3. On the right sidebar, next to Reference, select Copy Reference ().

You can now paste the reference into another description or comment.

Read more about issue references in GitLab-Flavored Markdown.

Copy issue email address

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:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues, then select your issue to view it.
3. On the right sidebar, next to Issue email, select Copy Reference ().

Assignees

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

Change assignee on an issue

Prerequisites:

• You must have at least the Reporter role for the project.

To change the assignee on an issue:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues, then select your issue to view it.
3. On the right sidebar, in the Assignee section, select Edit.
4. From the dropdown list, select the user to add as an assignee.
5. Select any area outside the dropdown list.

The assignee is changed without having to refresh the page.

Similar issues

To prevent duplication of issues on the same topic, GitLab searches for similar issues when you create a new issue.

Prerequisites:

• GraphQL must be enabled.

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.

Health status

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.

Change health status of an issue

Prerequisites:

• You must have at least the Reporter role for the project.

To edit health status of an issue:

1. On the left sidebar, select Search or go to and find your project.
2. Select Plan > Issues, then select your issue to view it.
3. On the right sidebar, in the Health status section, select Edit.

4. From the dropdown list, select the status to add to this issue:

   • On track (green)
   • Needs attention (amber)
   • At risk (red)

You can see the issue’s health status in:

• The Issues page
• Epic tree
• Issue cards in issue boards

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.

Publish an issue

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.

Issue-related quick actions

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:

• Add or remove a Zoom meeting (/zoom and /remove_zoom).
• Publish an issue (/publish).
• Clone an issue to the same or another project (/clone).
• Close an issue and mark as a duplicate of another issue (/duplicate).
• Copy labels and milestone from another merge request or issue in the project (/copy_metadata).