Tracker issues as work items
The Work items control ties a change to the task it was made for. When a company uses the built-in tracker, those tasks can be tracker issues: a merge request that mentions PAY-12 is linked to issue PAY-12 of the tracker, and in Enforce mode cannot merge until it names one that exists. This page covers what is particular to the built-in tracker; the control itself is described on Work items.
When it applies
Work items are looked up in the tracker linked to the merge request's VCS connection (see VCS connection settings). Built-in tracker issues are work items when that tracker is a built-in tracker connection and the change policy's Work items control is Report or Enforce.
Tasks are usually kept in a Manual project, where people create issues by hand (see Two kinds of project). Any project of the company counts, except the one where change approvals are created.
How keys are found
The policy's Look for keys in decides which texts are searched: Commit messages, Title, Description (the default three) and Branch name. Then:
- A key is a project prefix starting with a letter, a hyphen and a number, as tracker keys are:
PAY-12(a project's prefix always starts with a letter). Case does not matter (feature/pay-12-loginfindsPAY-12), and keys are kept in upper case. The tracker settings' Key pattern can replace this with a regular expression of your own (see Built-in tracker). - Without Work item projects in the tracker settings, only keys whose prefix is one of the company's tracker projects (not archived) count, so text such as
SHA-256is not taken for a work item. With Work item projects, only keys of the projects listed there count; the list offers the company's tracker projects that are not archived. - Keys of the tracker settings' Project, where change approvals are created, never count: a change approval is not a task.
- Each key counts once, however often it appears.
What Enforce checks
In Enforce mode, each key found is looked up among the company's tracker issues:
| Check | Built-in tracker specifics |
|---|---|
| The issue exists | An issue with that key in any tracker project of the company. Otherwise "PAY-12 does not exist" |
| It is in an allowed status (when the policy's Allowed statuses is set) | The status is the issue's state name, for example In Progress; it matches ignoring case |
| It is under the reuse limit (when Reuse limit is set) | Counted as for any tracker: merged merge requests of the company that referenced it |
The full rules, messages and the reuse reset are on Work items.
On the merge request page the Issue tracker card lists the work items; each links to the board of its tracker project.
Copying fields into the change approval
The tracker settings' Field mappings copy values from the work items into the change approval when it is opened (see Fields for Source, Target and Strategy). With the built-in tracker:
| Setting | What to enter |
|---|---|
| Source (work item field) | One of summary, description, state (or status), issue_type, assignee, reporter, or the key of a custom field of the work item's project (as a Jira field is named by its ID). The assignee and reporter are given by display name; a User or Users (multi) custom field gives the people's user names, so it fills a User field of the change approval with the same people. Other names, and fields the work item leaves empty, give no value |
| Target (change approval field) | The key of a custom field of the project where change approvals are created (see Custom fields). Values for keys the project does not have are dropped |
Related pages
- Work items: modes, settings, the reuse limit and what the merge request shows.
- Built-in tracker: Work item projects and Key pattern.
- Tracker, Issue page.