ContextQMD
Back to Gitlabhq

Create an issue

doc/user/project/issues/create_issues.md

18.11.210.4 KB
Original Source

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

When you create an 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.

You can create an issue in many ways in GitLab:

From a project

Prerequisites:

  • You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for the project.

To create an issue:

  1. In the top bar, select Search or go to and find your project.

  2. Either:

    • In the left sidebar, select Plan > Work items, and then, in the upper-right corner, select New item.
    • In the upper-right corner, select the plus sign ({{< icon name="plus" >}}) and then, under In this project, select New work item.

  3. From the Type dropdown list, select Issue if it is not already selected.

  4. Complete the fields.

  5. Select Create issue.

The newly created issue opens.

From a group

Issues belong to projects, but when you're in a group, you can access and create issues that belong to the projects in the group.

Prerequisites:

  • You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for the project in the group.

To create an issue from a group:

  1. In the top bar, select Search or go to and find your group.
  2. Select Plan > Work items.
  3. In the upper-right corner, select Select project to create issue.
  4. Select the project you'd like to create an issue for. The button now reflects the selected project.
  5. Select New issue in <project name>.
  6. Complete the fields.
  7. Select Create issue.

The newly created issue opens.

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

From another issue or incident

You can create a new issue from an existing one. The two issues can then be marked as related.

Prerequisites:

  • You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for the project.

To create an issue from another issue:

  1. In an existing issue, select Issue actions ({{< icon name="ellipsis_v" >}}).
  2. Select New related issue.
  3. Complete the fields. The new issue form has a Relate to issue #123 checkbox, where 123 is the ID of the issue of origin. If you keep this checkbox checked, the two issues become linked.
  4. Select Create issue.

The newly created issue opens.

From an issue board

You can create a new issue from an issue board.

Prerequisites:

  • You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role for the project.

To create an issue from a project issue board:

  1. In the top bar, select Search or go to and find your project.
  2. Select Plan > Issue boards.
  3. At the top of a board list, select Create new issue ({{< icon name="plus-square" >}}).
  4. Enter the issue's title.
  5. Select Create issue.

To create an issue from a group issue board:

  1. In the top bar, select Search or go to and find your group.
  2. Select Plan > Issue boards.
  3. At the top of a board list, select Create new issue ({{< icon name="plus-square" >}}).
  4. Enter the issue's title.
  5. Under Projects, select the project in the group that the issue should belong to.
  6. Select Create issue.

The issue is created and shows up in the board list. It shares the list's characteristic, so, for example, if the list is scoped to a label Frontend, the new issue also has this label.

By sending an email

{{< history >}}

  • Email a new issue to this project renamed to Email issue to this project in GitLab 18.6.

{{< /history >}}

You can send an email to create an issue in a project on the project's Issues page.

Prerequisites:

To email an issue to a project:

  1. In the top bar, select Search or go to and find your project.
  2. Select Plan > Work items.
  3. In the upper-right corner, select More actions ({{< icon name="ellipsis_v" >}}), then select Email work item to this project.
  4. To copy the email address, select Copy ({{< icon name="copy-to-clipboard" >}}).
  5. From your email client, send an email to this address. The subject is used as the title of the new issue, and the email body becomes the description. You can use Markdown and quick actions.

A new issue is created, with your user as the author. You can save this address as a contact in your email client to use it again.

[!warning] The email address you see is a private email address, generated just for you. Keep it to yourself, because anyone who knows it can create issues or merge requests as if they were you.

To regenerate the email address:

  1. On the Issues page, select Email issue to this project.
  2. Select reset this token.

Using a URL with prefilled values

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.

To build the URL to create an issue with prefilled values, combine:

  1. The project's or group's Issues page URL, followed by /new. For example: https://gitlab.com/gitlab-org/gitlab/-/issues/new

  2. ? to start listing parameters.

  3. URL parameter, followed by = and value. For example: issue[title]=My%20test%20issue.

  4. Optional. & to join more parameters.

FieldURL parameterNotes
Titleissue[title]Must be URL-encoded.
Issue typeissue[issue_type]Either incident or issue.
Description template (issues, incidents, and merge requests)issuable_templateMust be URL-encoded.
Description template (tasks, OKRs, issues, and epics.description_templateMust be URL-encoded. Introduced in GitLab 17.9.
Descriptionissue[description]Must be URL-encoded. If used in combination with issuable_template or a default issue template, the issue[description] value overwrites the template.
Confidentialissue[confidential]If true, the issue is marked as confidential.
Relate to…add_related_issueA numeric issue ID. If present, the issue form shows a Relate to checkbox to optionally link the new issue to the specified existing issue.

In GitLab 17.8 and later, when you select an issue template, the URL changes to show the template used.

Adapt these examples to form your new issue URL with prefilled fields. To create an issue in the GitLab project:

  • With a prefilled title and description:

    plaintext
    https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Whoa%2C%20we%27re%20half-way%20there&issue[description]=Whoa%2C%20livin%27%20in%20a%20URL

  • With a prefilled title and description template:

    plaintext
    https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Feature%20Proposal%20-%20basic

  • With a prefilled title, description, and marked as confidential:

    plaintext
    https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea&issue[confidential]=true

Using Service Desk

To offer email support, enable Service Desk for your project.

Now, when your customer sends a new email, a new issue can be created in the appropriate project and followed up from there.

Fields in the new issue form

{{< history >}}

{{< /history >}}

When you're creating a new issue, you can complete the following fields: