316 lines
14 KiB
Markdown
316 lines
14 KiB
Markdown
---
|
|
stage: Plan
|
|
group: Project Management
|
|
info: 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
|
|
|
|
[GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and
|
|
planning work in GitLab.
|
|
|
|
Key actions for issues include:
|
|
|
|
- [Creating issues](#create-a-new-issue)
|
|
- [Moving issues](#moving-issues)
|
|
- [Closing issues](#closing-issues)
|
|
- [Deleting issues](#deleting-issues)
|
|
- [Promoting issues](#promote-an-issue-to-an-epic) **(PREMIUM)**
|
|
|
|
## Create a new issue
|
|
|
|
When you create a new issue, you are prompted to fill in the [data and fields of the issue](issue_data_and_actions.md),
|
|
as illustrated below. If you know the values you want to assign to an issue, you can use the
|
|
[Quick actions](../quick_actions.md) feature to input values.
|
|
|
|
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**:
|
|
|
|
![New issue from the issue list view](img/new_issue_from_tracker_list.png)
|
|
|
|
- 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:
|
|
|
|
![New issue from an open issue](img/new_issue_from_open_issue_v13_6.png)
|
|
|
|
- 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:
|
|
|
|
![New issue from a project's dashboard](img/new_issue_from_projects_dashboard.png)
|
|
|
|
- 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.
|
|
|
|
![From the issue board](img/new_issue_from_issue_board.png)
|
|
|
|
### Elements of the New Issue form
|
|
|
|
> Ability to add the new issue to an epic [was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13847) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.1.
|
|
|
|
![New issue from the issues list](img/new_issue_v13_1.png)
|
|
|
|
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 **(PREMIUM)**
|
|
- Due date
|
|
- Milestone
|
|
- Labels
|
|
|
|
### New issue from the group-level Issue Tracker
|
|
|
|
Go to the Group dashboard and click **Issues** in the sidebar to visit the Issue Tracker
|
|
for all projects in your Group. Select the project you'd like to add an issue for
|
|
using the dropdown button at the top-right of the page.
|
|
|
|
![Select project to create issue](img/select_project_from_group_level_issue_tracker.png)
|
|
|
|
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.
|
|
|
|
![Create issue from group-level issue tracker](img/create_issue_from_group_level_issue_tracker.png)
|
|
|
|
### New issue via Service Desk
|
|
|
|
Enable [Service Desk](../service_desk.md) for your project and offer email support.
|
|
By doing so, 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](../../../administration/incoming_email.md)
|
|
configured and there is at least one issue in the issue list.
|
|
|
|
![Bottom of a project issues page](img/new_issue_from_email.png)
|
|
|
|
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](../../markdown.md) and [quick actions](../quick_actions.md) 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, or create issues with certain
|
|
fields prefilled.
|
|
|
|
The title, description, description template, and confidential fields can be prefilled
|
|
using this method. You cannot pre-fill both the description and description template
|
|
fields in the same URL because a description template also populates the description
|
|
field.
|
|
|
|
| Field | URL Parameter Name | Notes |
|
|
|----------------------|-----------------------|-------------------------------------------------------|
|
|
| title | `issue[title]` | |
|
|
| description | `issue[description]` | |
|
|
| description template | `issuable_template` | |
|
|
| 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`
|
|
|
|
## 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.
|
|
|
|
![move issue - button](img/sidebar_move_issue.png)
|
|
|
|
### Moving Issues in Bulk
|
|
|
|
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](../../../raketasks/backup_restore.md#back-up-gitlab) before
|
|
attempting any changes in the console.
|
|
|
|
```ruby
|
|
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
|
|
using the close button:
|
|
|
|
![close issue - button](img/button_close_issue_v13_6.png)
|
|
|
|
You can also close an issue from the [Issue Boards](../issue_board.md) by dragging an issue card
|
|
from its list and dropping it into the **Closed** list.
|
|
|
|
![close issue from the Issue Board](img/close_issue_from_board.gif)
|
|
|
|
### 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](#default-closing-pattern),
|
|
all issues referenced in the matched text are closed. This happens when the commit
|
|
is pushed to a project's [**default** branch](../repository/branches/index.md#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](related_issues.md),
|
|
but is not closed automatically.
|
|
|
|
![merge request closing issue when merged](img/merge_request_closes_issue.png)
|
|
|
|
If the issue is in a different repository than the MR, add the full URL for the issue(s):
|
|
|
|
```markdown
|
|
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.
|
|
|
|
#### Default closing pattern
|
|
|
|
When not specified, this default issue closing pattern is used:
|
|
|
|
```shell
|
|
\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:
|
|
|
|
```plaintext
|
|
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](https://gitlab.com/gitlab-org/gitlab/-/issues/19754) in GitLab 12.7.
|
|
|
|
The automatic issue closing feature can be disabled on a per-project basis
|
|
in the [project's repository settings](../settings/index.md). Referenced
|
|
issues are still displayed, but are not closed automatically.
|
|
|
|
![disable issue auto close - settings](img/disable_issue_auto_close.png)
|
|
|
|
This only applies to issues affected by new merge requests or commits. Already
|
|
closed issues remain as-is. Disabling automatic issue closing only affects merge
|
|
requests *in* the project and does not prevent other projects from closing it
|
|
via cross-project issues.
|
|
|
|
#### Customizing the issue closing pattern **(CORE ONLY)**
|
|
|
|
In order to change the default issue closing pattern, GitLab administrators must edit the
|
|
[`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md)
|
|
of your installation.
|
|
|
|
## Deleting issues
|
|
|
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2982) in GitLab 8.6.
|
|
|
|
Users with [project owner permission](../../permissions.md) can delete an issue by
|
|
editing it and clicking on the delete button.
|
|
|
|
![delete issue - button](img/delete_issue.png)
|
|
|
|
## Promote an issue to an epic **(PREMIUM)**
|
|
|
|
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6.
|
|
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/37081) to [GitLab Premium](https://about.gitlab.com/pricing/) in 12.8.
|
|
> - Promoting issues to epics via the UI [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233974) in [GitLab Premium](https://about.gitlab.com/pricing/) 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.
|
|
1. Select **Promote to epic**.
|
|
|
|
Alternatively, you can use the `/promote` [quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics).
|
|
|
|
Read more about promoting an issue to an epic on the [Manage epics page](../../group/epics/manage_epics.md#promote-an-issue-to-an-epic).
|
|
|
|
## Add an issue to an iteration **(STARTER)**
|
|
|
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216158) in [GitLab Starter](https://about.gitlab.com/pricing/) 13.2.
|
|
|
|
To add an issue to an [iteration](../../group/iterations/index.md):
|
|
|
|
1. In an issue sidebar, click **Edit** next to **Iteration**. A dropdown appears.
|
|
1. Click an iteration you'd like to associate this issue with.
|
|
|
|
You can also use the `/iteration`
|
|
[quick action](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics)
|
|
in a comment or description field.
|