@@ -111,7 +111,7 @@ The following documentation relates to the DevOps **Plan** stage:
| [Discussions](user/discussions/index.md) | Threads, comments, and resolvable discussions in issues, commits, and merge requests. |
| [Due Dates](user/project/issues/due_dates.md) | Keep track of issue deadlines. |
| [Epics](user/group/epics/index.md)**[ULTIMATE]** | Tracking groups of issues that share a theme. |
| [Issues](user/project/issues/index.md), including [confidential issues](user/project/issues/confidential_issues.md),<br/>[issue and merge request templates](user/project/description_templates.md),<br/>and [moving issues](user/project/issues/moving_issues.md) | Project issues, restricting access to issues, create templates for submitting new issues and merge requests, and moving issues between projects. |
| [Issues](user/project/issues/index.md), including [confidential issues](user/project/issues/confidential_issues.md),<br/>[issue and merge request templates](user/project/description_templates.md),<br/>and [moving issues](user/project/issues/managing_issues.md#moving-issues) | Project issues, restricting access to issues, create templates for submitting new issues and merge requests, and moving issues between projects. |
| [Labels](user/project/labels.md) | Categorize issues or merge requests with descriptive labels. |
| [Milestones](user/project/milestones/index.md) | Set milestones for delivery of issues and merge requests, with optional due date. |
| [Project Issue Board](user/project/issue_board.md) | Display issues on a Scrum or Kanban board. |
@@ -117,7 +117,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
- Instances. **[PREMIUM ONLY]**
-[Auditor users](auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance. **[PREMIUM ONLY]**
-[Incoming email](incoming_email.md): Configure incoming emails to allow
users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/create_new_issue.md#new-issue-via-email) and
users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/managing_issues.md#new-issue-via-email) and
[merge requests by email](../user/project/merge_requests/index.md#create-new-merge-requests-by-email), and to enable [Service Desk](../user/project/service_desk.md).
-[Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a
basic Postfix mail server with IMAP authentication on Ubuntu for incoming
@@ -22,7 +22,7 @@ The following are guides to basic GitLab functionality:
-[Fork a project](fork-project.md), to duplicate projects so they can be worked on in parallel.
-[Add a file](add-file.md), to add new files to a project's repository.
-[Add an image](add-image.md), to add new images to a project's repository.
-[Create an issue](../user/project/issues/create_new_issue.md), to start collaborating within a project.
-[Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue), to start collaborating within a project.
-[Create a merge request](add-merge-request.md), to request changes made in a branch be merged into a project's repository.
- See how these features come together in the [GitLab Flow introduction video](https://youtu.be/InKNIvky2KE) and [GitLab Flow page](../workflow/gitlab_flow.md).
@@ -156,6 +156,6 @@ Learn more about Cycle Analytics in the following resources:
[environment]:../../ci/yaml/README.md#environment
[GitLab flow]:../../workflow/gitlab_flow.md
[idea to production]:https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab
Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues.
When you create a new issue, you'll be prompted to fill in
the information illustrated on the image below.
Read through the [issue data and actions documentation](issue_data_and_actions.md#parts-of-an-issue)
to understand these fields one by one.
## New issue from the Issue Tracker
Navigate to your **Project's Dashboard** > **Issues** > **New Issue** to create a new issue:
## New issue from an opened issue
From an **opened issue** in your project, click **New Issue** to create a new
issue in the same project:
## New issue from the project's dashboard
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 the Issue Board
From an Issue Board, create a new issue by clicking on the plus sign (**+**) on the top of a list.
It opens a new issue for that project labeled after its respective list.
## New issue via email
At the bottom of a project's Issues List page, a link to **Email a new issue to this project**
is displayed if your GitLab instance has [incoming email](../../../administration/incoming_email.md) configured.
When you click this link, an email address is displayed which belongs to you for creating issues in this project.
You can save this address as a contact in your email client for easy acceess.
CAUTION: **Caution:**
This is a private email address, generated just for you. **Keep it to yourself**,
as anyone who gets ahold of it can create issues or merge requests as if they
were you. If the address is compromised, or you'd like it to be regenerated for
any reason, click **Email a new issue to this project** again and click the reset link.
Sending an email to this address will create a new issue on your behalf 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: **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 Service Desk **[PREMIUM]**
Enable [Service Desk](../service_desk.md) to 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 from the group-level Issue Tracker
Head 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.
We'll keep track of the project you selected most recently, and use it as 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 URL with prefilled fields
You can link directly to the new issue page for a given project, with prefilled
field values using query string parameters in a URL. This is useful for embedding
a URL in an external HTML page, and also certain scenarios where you want the user to
create an issue with certain fields prefilled.
The title, description, and description template fields can be prefilled using
this method. The description and description template fields cannot be pre-entered
in the same URL (since a description template just populates the description field).
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-entered title
and a pre-entered description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea`
- For a new issue in the GitLab Community Edition project with a pre-entered title
and a pre-entered description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal`
This document was moved to [another location](managing_issues.md#create-a-new-issue).
NOTE: **Note:** Linking your first commit to your issue is going to be relevant
for tracking your process with [GitLab Cycle Analytics](https://about.gitlab.com/features/cycle-analytics/).
It will measure the time taken for planning the implementation of that issue,
which is the time between creating an issue and making the first commit.
...
...
@@ -35,14 +34,13 @@ which is the time between creating an issue and making the first commit.
Mentioning related issues in merge requests and other issues is useful
for your team members and collaborators to know that there are opened
issues around that same idea.
issues regarding the same topic.
You do that as explained above, when
[mentioning an issue from a commit message](#from-commit-messages).
You do that as explained above, when [mentioning an issue from a commit message](#from-commit-messages).
When mentioning the issue "A" in issue "B", the issue "A" will also
display a notification in its tracker. The same is valid for mentioning
issues in merge requests.
When mentioning issue `#111` in issue `#222`, issue `#111` will also display a notification
in its tracker. That is, you only need to mention the relationship once for it to
display in both issues. The same is valid when mentioning issues in [merge requests](#from-merge-requests).
...
...
@@ -53,10 +51,7 @@ they do for [related issues](#from-related-issues).
When you mention an issue in a merge request description, it will simply
[link the issue and merge request together](#from-related-issues). Additionally,
you can also [set an issue to close as soon as the merge request is merged](closing_issues.md#via-merge-request).
you can also [set an issue to close automatically](managing_issues.md#closing-issues-automatically)
as soon as the merge request is merged.
### Close an issue by merging a merge request
To [close an issue when a merge request is merged](closing_issues.md#via-merge-request), use the [automatic issue closing pattern](automatic_issue_closing.md).
@@ -6,8 +6,9 @@ Issues are the fundamental medium for collaborating on ideas and planning work i
The GitLab issue tracker is an advanced tool for collaboratively developing ideas, solving problems, and planning work.
Issues can allow you, your team, and your collaborators to share and discuss proposals before and during their implementation.
However, they can be used for a variety of other purposes, customized to your needs and workflow.
Issues can allow you, your team, and your collaborators to share and discuss proposals
before, and during, their implementation. However, they can be used for a variety of
other purposes, customized to your needs and workflow.
Issues are always associated with a specific project, but if you have multiple projects in a group,
you can also view all the issues collectively at the group level.
...
...
@@ -17,13 +18,15 @@ you can also view all the issues collectively at the group level.
- Discussing the implementation of a new idea
- Tracking tasks and work status
- Accepting feature proposals, questions, support requests, or bug reports
- Elaborating new code implementations
- Elaborating on new code implementations
See also the blog post "[Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/)".
See also [Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/).
## Parts of an issue
Issues contain a variety of content and metadata, enabling a large range of flexibility in how they are used. Each issue can contain the following attributes, though some items may remain unset.
Issues contain a variety of content and metadata, enabling a large range of flexibility
in how they are used. Each issue can contain the following attributes, though not all items
must be set.
<tableclass="borderless-table fixed-table">
<tr>
...
...
@@ -70,23 +73,36 @@ Issues contain a variety of content and metadata, enabling a large range of flex
## Viewing and managing issues
While you can view and manage the full detail of an issue at its URL, you can also work with multiple issues at a time using the Issues List, Issue Boards, Epics **[ULTIMATE]**, and issue references.
While you can view and manage the full details of an issue on the [issue page](#issue-page),
you can also work with multiple issues at a time using the [Issues List](#issues-list),
[Issue Boards](#issue-boards), Issue references, and [Epics](#epics-ultimate)**[ULTIMATE]**.
On an issue’s page, you can view all aspects of the issue, and you can also modify them if you you have the necessary [permissions](../../permissions.md).
For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page.
On an issue's page, you can view [all aspects of the issue](issue_data_and_actions.md),
and modify them if you you have the necessary [permissions](../../permissions.md).
### Issues list
On the Issues List, you can view all issues in the current project, or from multiple projects when opening the Issues List from the higher-level group context. Filter the issue list by [any search query](../../search/index.md#issues-and-merge-requests-per-project) and/or specific metadata, such as label(s), assignees(s), status, and more. From this view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues.
On the Issues List, you can view all issues in the current project, or from multiple
projects when opening the Issues List from the higher-level group context. Filter the
issue list with a [search query](../../search/index.md#issues-and-merge-requests-per-project),
including specific metadata, such as label(s), assignees(s), status, and more. From this
view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues.
For more information on interacting with Issues, see the [Issue Data and Actions](issue_data_and_actions.md) page.
For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page
for a rundown of all the fields and information in an issue.
For sorting by issue priority, see [Label Priority](../labels.md#label-priority).
...
...
@@ -94,44 +110,55 @@ For sorting by issue priority, see [Label Priority](../labels.md#label-priority)
Issue boards are Kanban boards with columns that display issues based on their labels or their assignees**[PREMIUM]**. They offer the flexibility to manage issues using highly customizable workflows.
[Issue boards](../issue_board.md) are Kanban boards with columns that display issues based on their labels
or their assignees**[PREMIUM]**. They offer the flexibility to manage issues using
highly customizable workflows.
You can reorder issues within a column, or drag an issue card to another column; its associated label or assignee will change to match that of the new column. The entire board can also be filtered to only include issues from a certain milestone or an overarching label.
For more information, see the [Issue Boards](../issue_board.md) page.
You can reorder issues within a column. If you drag an issue card to another column, its
associated label or assignee will change to match that of the new column. The entire
board can also be filtered to only include issues from a certain milestone or an overarching
label.
### Epics **[ULTIMATE]**
Epics let you manage your portfolio of projects more efficiently and with less effort by tracking groups of issues that share a theme, across projects and milestones.
For more information, see the [Epics](../../group/epics/index.md) page.
[Epics](../../group/epics/index.md) let you manage your portfolio of projects more
efficiently and with less effort by tracking groups of issues that share a theme, across
projects and milestones.
### Related issues **[STARTER]**
You can mark two issues as related, so that when viewing each one, the other is always listed in its Related Issues section. This can help display important context, such as past work, dependencies, or duplicates.
For more information, see [Related Issues](related_issues.md).
You can mark two issues as related, so that when viewing one, the other is always
listed in its [Related Issues](related_issues.md) section. This can help display important
context, such as past work, dependencies, or duplicates.
### Crosslinking issues
When you reference an issue from another issue or merge request by including its URL or ID, the referenced issue displays a message in the Activity stream about the reference, with a link to the other issue or MR.
You can [crosslink issues](crosslinking_issues.md) by referencing an issue from another
issue or merge request by including its URL or ID. The referenced issue displays a
message in the Activity stream about the reference, with a link to the other issue or MR.
For more information, see [Crosslinking issues](crosslinking_issues.md).
### Similar issues
## Issue actions
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22866) in GitLab 11.6.
-[Create an issue](create_new_issue.md)
-[Create an issue from a template](../../project/description_templates.md#using-the-templates)
-[Close an issue](closing_issues.md)
-[Move an issue](moving_issues.md)
-[Delete an issue](deleting_issues.md)
-[Create a merge request from an issue](issue_data_and_actions.md#22-create-merge-request)
To prevent duplication of issues for the same topic, GitLab searches for similar issues
when new issues are being created.
When typing in the title in the new issue form, GitLab searches titles and descriptions
across all issues the user has access to in the current project. Up 5 similar issues,
sorted by most recently updated, are displayed below the title box. Note that this feature
requires [GraphQL](../../../api/graphql/index.md) to be enabled.
## Advanced issue management
-[Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues in order to change their status, assignee, milestone, or labels in bulk.
## Other Issue actions
-[Create an issue from a template](../../project/description_templates.md#using-the-templates)
-[Set a due date](due_dates.md)
-[Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues
in order to change their status, assignee, milestone, or labels in bulk.
-[Import issues](csv_import.md)
-[Export issues](csv_export.md)**[STARTER]**
-[Issues API](../../../api/issues.md)
- Configure an [external issue tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine,
or Bugzilla.
- Configure an [external issue tracker](../../../integration/external-issue-tracker.md)
[GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and
planning work in GitLab. [Creating](#create-a-new-issue), [moving](#moving-issues),
[closing](#closing-issues), and [deleting](#deleting-issues) are key actions that
you can do with issues.
## Create a new Issue
When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md#parts-of-an-issue), as illustrated below.
### Accessing the new Issue form
There are many ways to get to the new Issue form from within a project:
- Navigate to your **Project's Dashboard** > **Issues** > **New Issue**:
- From an **opened issue** in your project, 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.
### 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.
We'll keep track of the project you selected most recently, and use it as 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 **[PREMIUM]**
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, if your GitLab instance has [incoming email](../../../administration/incoming_email.md)
configured.
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 easy acceess.
CAUTION: **Caution:**
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'd like it to be regenerated for
any reason, click **Email a new issue to this project** again and click the reset link.
Sending an email to this address will create a new issue in your name 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: **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
You can link directly to the new issue page for a given project, with prefilled
field values using query string parameters in a URL. This is useful for embedding
a URL in an external HTML page, and also certain scenarios where you want the user to
create an issue with certain fields prefilled.
The title, description, and description template fields can be prefilled using
this method. You cannot pre-fill both the description and description template fields
in the same URL (since a description template also populates the description field).
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-ce/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-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal`
## Moving Issues
Moving an issue will copy it to a new location (project), and close it in the old project,
but it will not be deleted. There will also be a system note added to both issues
indicating where it came from and went to.
The "Move issue" button is at the bottom of the right-sidebar when viewing the issue.
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 will move all the issues from one project to another that are not in status **closed**.
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](https://docs.gitlab.com/ee/raketasks/backup_restore.html#creating-a-backup-of-the-gitlab-system) 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')
@@ -23,7 +23,7 @@ With GitLab merge requests, you can:
- Build, test, and deploy your code in a per-branch basis with built-in [GitLab CI/CD](../../../ci/README.md)
- Prevent the merge request from being merged before it's ready with [WIP MRs](#work-in-progress-merge-requests)
- View the deployment process through [Pipeline Graphs](../../../ci/pipelines.md#visualizing-pipelines)
-[Automatically close the issue(s)](../../project/issues/closing_issues.md#via-merge-request) that originated the implementation proposed in the merge request
-[Automatically close the issue(s)](../../project/issues/managing_issues.md#closing-issues-automatically) that originated the implementation proposed in the merge request
- Assign it to any registered user, and change the assignee how many times you need
- Assign a [milestone](../../project/milestones/index.md) and track the development of a broader implementation
- Organize your issues and merge requests consistently throughout the project with [labels](../../project/labels.md)
