diff options
Diffstat (limited to 'doc/user/project/integrations/custom_issue_tracker.md')
| -rw-r--r-- | doc/user/project/integrations/custom_issue_tracker.md | 52 |
1 files changed, 30 insertions, 22 deletions
diff --git a/doc/user/project/integrations/custom_issue_tracker.md b/doc/user/project/integrations/custom_issue_tracker.md index 9cc4e980212..19beafd6663 100644 --- a/doc/user/project/integrations/custom_issue_tracker.md +++ b/doc/user/project/integrations/custom_issue_tracker.md @@ -4,35 +4,43 @@ group: Ecosystem 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 --- -# Custom Issue Tracker service **(FREE)** +# Custom issue tracker service **(FREE)** -To enable the Custom Issue Tracker integration in a project: +Use a custom issue tracker that is not in the integration list. -1. Go to **Settings > Integrations**. -1. Click **Custom Issue Tracker** -1. Fill in the tracker's details, such as title, description, and URLs. - You can edit these fields later as well. +To enable a custom issue tracker in a project: - These are some of the required fields: +1. Go to the [Integrations page](overview.md#accessing-integrations). +1. Select **Custom issue tracker**. +1. Select the checkbox under **Enable integration**. +1. Fill in the required fields: - | Field | Description | - | --------------- | ----------- | - | **Project URL** | The URL to the project in the custom issue tracker. | - | **Issues URL** | The URL to the issue in the issue tracker project that is linked to this GitLab project. Note that the `issues_url` requires `:id` in the URL. This ID is used by GitLab as a placeholder to replace the issue number. For example, `https://customissuetracker.com/project-name/:id`. | - | **New issue URL** | Currently unused. Planned to be changed in a future release. | + - **Project URL**: The URL to view all the issues in the custom issue tracker. + - **Issue URL**: The URL to view an issue in the custom issue tracker. The URL must contain `:id`. + GitLab replaces `:id` with the issue number (for example, + `https://customissuetracker.com/project-name/:id`, which becomes `https://customissuetracker.com/project-name/123`). + - **New issue URL**: + <!-- The line below was originally added in January 2018: https://gitlab.com/gitlab-org/gitlab/-/commit/778b231f3a5dd42ebe195d4719a26bf675093350 --> + **This URL is not used and removal is planned in a future release.** + Enter any URL here. + For more information, see [issue 327503](https://gitlab.com/gitlab-org/gitlab/-/issues/327503). -1. Click **Test settings and save changes**. +1. Select **Save changes** or optionally select **Test settings**. -After you configure and enable the Custom Issue Tracker service, you see a link on the GitLab -project pages that takes you to that custom issue tracker. +After you configure and enable the custom issue tracker service, a link appears on the GitLab +project pages. This link takes you to the custom issue tracker. -## Referencing issues +## Reference issues in a custom issue tracker -Issues are referenced with `<ANYTHING>-<ID>` (for example, `PROJECT-143`), where `<ANYTHING>` can be any string in CAPS, and `<ID>` -is a number used in the target project of the custom integration. +You can reference issues in a custom issue tracker using: -`<ANYTHING>` is a placeholder to differentiate against GitLab issues, which are referenced with `#<ID>`. You can use a project name or project key to replace it for example. +- `#<ID>`, where `<ID>` is a number (for example, `#143`). +- `<PROJECT>-<ID>` (for example `API_32-143`) where: + - `<PROJECT>` starts with a capital letter, followed by capital letters, numbers, or underscores. + - `<ID>` is a number. -When building the hyperlink, the `<ANYTHING>` part is ignored, and links always point to the address -specified in `issues_url`, so in the example above, `PROJECT-143` would refer to -`https://customissuetracker.com/project-name/143`. +The `<PROJECT>` part is ignored in links, which always point to the address specified in **Issue URL**. + +We suggest using the longer format (`<PROJECT>-<ID>`) if you have both internal and external issue +trackers enabled. If you use the shorter format, and an issue with the same ID exists in the +internal issue tracker, the internal issue is linked. |