gitlab-org--gitlab-foss/doc/user/project/issues/managing_issues.md

stage	group	info
Plan	Project Management	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Managing issues (FREE)

GitLab Issues are the fundamental medium for collaborating on ideas and planning work in GitLab.

Key actions for issues include:

• Creating issues
• Moving issues
• Closing issues
• Deleting issues
• Promoting issues (PREMIUM)

Create a new issue

When you create a new issue, you are prompted to enter the fields of the issue. If you know the values you want to assign to an issue, you can use quick actions to enter them.

While creating an issue, you can associate it to an existing epic from current group by selecting it using Epic dropdown.

Accessing the New Issue form

There are many ways to get to the New Issue form from a project's page:

• Navigate to your Project's Dashboard > Issues > New Issue:

  

• From an open issue in your project, click the vertical ellipsis ({ellipsis_v}) button to open a dropdown menu, and then click New Issue to create a new issue in the same project:

  

• From your Project's Dashboard, click the plus sign (+) to open a dropdown menu with a few options. Select New Issue to create an issue in that project:

  

• From an issue board, create a new issue by clicking on the plus sign (+) at the top of a list. It opens a new issue for that project, pre-labeled with its respective list.

  

Elements of the New Issue form

Ability to add the new issue to an epic was introduced in GitLab Premium 13.1.

When you're creating a new issue, these are the fields you can fill in:

• Title
• Description
• Checkbox to make the issue confidential
• Assignee
• Weight
• Epic
• Due date
• Milestone
• Labels

New issue from the group-level issue tracker

To visit the issue tracker for all projects in your group:

1. Go to the group dashboard.
2. On the left sidebar, select Issues.
3. In the top-right, select the Select project to create issue button.
4. Select the project you'd like to create an issue for. The button now reflects the selected project.
5. Select the button to create an issue in the selected project.

The project you selected most recently becomes the default for your next visit. This should save you a lot of time and clicks, if you mostly create issues for the same project.

New issue via Service Desk

Enable Service Desk for your project and offer email support. Now, when your customer sends a new email, a new issue can be created in the appropriate project and followed up from there.

New issue via email

A link to Email a new issue to this project is displayed at the bottom of a project's Issues List page. The link is shown only if your GitLab instance has incoming email configured and there is at least one issue in the issue list.

When you click this link, an email address is generated and displayed, which should be used by you only, to create issues in this project. You can save this address as a contact in your email client for quick access.

WARNING: This is a private email address, generated just for you. Keep it to yourself, as anyone who knows it can create issues or merge requests as if they were you. If the address is compromised, or you want to regenerate it, click Email a new issue to this project, followed by reset it.

Sending an email to this address creates a new issue associated with your account for this project, where:

• The email subject becomes the issue title.
• The email body becomes the issue description.
• Markdown and quick actions are supported.

NOTE: In GitLab 11.7, we updated the format of the generated email address. However the older format is still supported, allowing existing aliases or contacts to continue working.

New issue via URL with prefilled fields

To link directly to the new issue page with prefilled fields, use query string parameters in a URL. You can embed a URL in an external HTML page to create issues with certain fields prefilled.

Field	URL Parameter Name	Notes
title	issue[title]
description	issue[description]	Cannot be used at the same time as issuable_template.
description template	issuable_template	Cannot be used at the same time as issue[description].
issue type	issue[issue_type]	Either incident or issue.
confidential	issue[confidential]	Parameter value must be true to set to confidential.

Follow these examples to form your new issue URL with prefilled fields.

• For a new issue in the GitLab Community Edition project with a pre-filled title and a pre-filled description, the URL would be https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea
• For a new issue in the GitLab Community Edition project with a pre-filled title and a pre-filled description template, the URL would be https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal
• For a new issue in the GitLab Community Edition project with a pre-filled title, a pre-filled description, and the confidential flag set, the URL would be https://gitlab.com/gitlab-org/gitlab-foss/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true

Edit an issue

You can edit an issue's title and description.

To edit an issue, select Edit title and description ({pencil}).

Bulk edit issues at the project level

• Assigning epic (introduced in GitLab 13.2.
• Editing health status introduced in GitLab 13.2.
• Editing iteration introduced in GitLab 13.9.

Users with permission level of Reporter or higher can manage issues.

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

• Status (open/closed)
• Assignee
• Epic
• Milestone
• Labels
• Health status
• Notification subscription
• Iteration

To update multiple project issues at the same time:

1. In a project, go to Issues > List.
2. Click Edit issues. A sidebar on the right-hand side of your screen appears with editable fields.
3. Select the checkboxes next to each issue you want to edit.
4. Select the appropriate fields and their values from the sidebar.
5. Click Update all.

Bulk edit issues at the group level

• Introduced in GitLab 12.1.
• Assigning epic (introduced in GitLab 13.2.
• Editing health status introduced in GitLab 13.2.
• Editing iteration introduced in GitLab 13.9.

Users with permission level of Reporter or higher can manage issues.

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

• Epic
• Milestone
• Labels
• Health status
• Iteration

To update multiple project issues at the same time:

1. In a group, go to Issues > List.
2. Click Edit issues. A sidebar on the right-hand side of your screen appears with editable fields.
3. Select the checkboxes next to each issue you want to edit.
4. Select the appropriate fields and their values from the sidebar.
5. Click Update all.

Moving issues

Moving an issue copies it to the target project, and closes it in the originating project. The original issue is not deleted. A system note, which indicates where it came from and went to, is added to both issues.

The "Move issue" button is at the bottom of the right-sidebar when viewing the issue.

Moving issues in bulk (FREE SELF)

If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script moves all issues that are not in status closed from one project to another.

To access rails console run sudo gitlab-rails console on the GitLab server and run the below script. Please be sure to change project, admin_user, and target_project to your values. We do also recommend creating a backup before attempting any changes in the console.

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(project, admin_user).execute(issue, target_project)
   else
      puts "issue with id: #{issue.id} and title: #{issue.title} was not moved"
   end
end; nil

Closing issues

When you decide that an issue is resolved, or no longer needed, you can close the issue. The issue is marked as closed but is not deleted.

To close an issue, you can do the following:

• Select Close issue:

  

• In an issue board, drag an issue card from its list into the Closed list.

  

Reopen a closed issue

To reopen a closed issue, select Reopen issue. A reopened issue is no different from any other open issue.

Closing issues automatically

When a commit or merge request resolves issues, the issues can be closed automatically when the commit reaches the project's default branch.

If a commit message or merge request description contains text matching a defined pattern, all issues referenced in the matched text are closed. This happens when the commit is pushed to a project's default branch, or when a commit or merge request is merged into it.

For example, if Closes #4, #6, Related to #5 is included in a Merge Request description, issues #4 and #6 are closed automatically when the MR is merged, but not #5. Using Related to flags #5 as a related issue, but is not closed automatically.

If the issue is in a different repository than the MR, add the full URL for the issue(s):

Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx>

For performance reasons, automatic issue closing is disabled for the very first push from an existing repository.

Alternatively, when you create a merge request from an issue, it inherits the issue's milestone and labels.

Default closing pattern

When not specified, this default issue closing pattern is used:

\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+))+)

This translates to the following 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

Note that %{issue_ref} is a complex regular expression defined inside the GitLab source code that can match references to:

• A local issue (#123).
• A cross-project issue (group/project#123).
• A link to an issue (https://gitlab.example.com/group/project/issues/123).

For example the following commit message:

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.

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. It works with multi-line commit messages as well as one-liners when used from the command line with git commit -m.

Disabling automatic issue closing

Introduced in GitLab 12.7.

The automatic issue closing feature can be disabled on a per-project basis in the project's repository settings. Referenced issues are still displayed, but are not closed automatically.

The automatic issue closing is also disabled in a project if the project has the issue tracker disabled. If you want to enable automatic issue closing, make sure to enable GitLab Issues.

This only applies to issues affected by new merge requests or commits. Already closed issues remain as-is. If issue tracking is enabled, disabling automatic issue closing only applies to merge requests attempting to automatically close issues within the same project. Merge requests in other projects can still close another project's issues.

Customizing the issue closing pattern (FREE SELF)

In order to change the default issue closing pattern, GitLab administrators must edit the gitlab.rb or gitlab.yml file of your installation.

Change the issue type

Users with the Developer role can change an issue's type. To do this, edit the issue and select an issue type from the Issue type selector menu:

• Issue
• Incident

Deleting issues

Users with the Owner role can delete an issue by editing it and selecting Delete issue.

Promote an issue to an epic (PREMIUM)

• Introduced in GitLab Ultimate 11.6.
• Moved to GitLab Premium in 12.8.
• Promoting issues to epics via the UI introduced in GitLab Premium 13.6.

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

To promote an issue to an epic:

1. In an issue, select the vertical ellipsis ({ellipsis_v}) button.
2. Select Promote to epic.

Alternatively, you can use the /promote quick action.

Read more about promoting an issue to an epic on the Manage epics page.

Add an issue to an iteration (PREMIUM)

• Introduced in GitLab 13.2.
• Moved to GitLab Premium in 13.9.

To add an issue to an iteration:

1. Go to your issue.
2. On the right sidebar, in the Iteration section, select Edit.
3. From the dropdown list, select the iteration to associate this issue with.
4. Select any area outside the dropdown list.

You can also use the /iteration quick action in a comment or description field.

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. Go to the issue.
2. On the right sidebar, next to Reference, select Copy Reference ({copy-to-clipboard}).

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

Read more about issue references in GitLab-Flavored Markdown.

Copy issue email address

Introduced in GitLab 13.8.

You can create a comment in an issue by sending an email.

To copy the issue's email address:

1. Go to the issue.
2. On the right sidebar, next to Issue email, select Copy Reference ({copy-to-clipboard}).

Sending an email to this address creates a comment containing the email body. To learn more about creating comments by sending an email and the necessary configuration, see Reply to a comment by sending email.

Real-time sidebar

• Introduced in GitLab 13.3. Disabled by default.
• Enabled on GitLab.com in GitLab 13.9.
• Enabled on self-managed in GitLab 14.5.

FLAG: On self-managed GitLab, by default this feature is available. To hide the feature per project or for your entire instance, ask an administrator to disable the feature flags named real_time_issue_sidebar and broadcast_issue_updates. On GitLab.com, this feature is available.

Assignees in the sidebar are updated in real time.

Assignee

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 an issue. When an issue is assigned to someone, it appears in their assigned issues list.

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.

To change the assignee on an issue:

1. Go to your issue.
2. On the right sidebar, in the Assignee section, select Edit.
3. From the dropdown list, select the user to add as an assignee.
4. Select any area outside the dropdown list.

Similar issues

Introduced in GitLab 11.6.

To prevent duplication of issues for the same topic, GitLab searches for similar issues when new issues are being created.

As you type in the title field of the New Issue page, GitLab searches titles and descriptions across all issues to 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 box. GraphQL must be enabled to use this feature.

Health status (ULTIMATE)

• Introduced in GitLab Ultimate 12.10.
• Health status of closed issues can't be edited in GitLab Ultimate 13.4 and later.
• Issue health status visible in issue lists introduced in GitLab Ultimate 13.6.
• Feature flag removed in GitLab 13.7.

To help you track issue statuses, you can assign a status to each issue. This marks issues as progressing as planned or needs attention to keep on schedule:

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

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 then see issue statuses in the issues list and the epic tree.

Publish an issue (ULTIMATE)

Introduced in GitLab 13.1.

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.