Work items
The Work items control ties a change to the business task it was made for: a tracker issue key such as PAY-123, referenced in the merge request's commit messages, title, description or branch name. In Report mode Merge Pilot records the work items it finds; in Enforce mode a merge request without a valid work item cannot merge.
The control is set per change policy, in the policy editor's Checks tab (row Work items). See Controls for how controls work together and Change policies for the editor.
Modes
| Mode (label in the UI) | API value | What it does | Effect on the merge gate |
|---|---|---|---|
| Off | off | Work items are not looked for | None |
| Report | record | The keys found are recorded and linked to the change approval; they are not checked in the tracker | None: the control always passes ("Linked: PAY-123." or "No work items referenced (recorded only).") |
| Enforce | required | At least one work item must be referenced, must exist in the tracker and, when set, be in an allowed status and under the reuse limit | Waiting while the keys are looked up or the tracker cannot be reached; Blocked when the check fails |
A new policy starts with Off. In Enforce mode the change approval is opened only once the work items check out, so approvers are not asked about a change that has no valid task yet. CI and scans still run meanwhile.
Settings
| Setting (label in the UI) | What it does | Default | Allowed values | Set where | Who can change it | API field |
|---|---|---|---|---|---|---|
| Mode (row Work items) | See Modes | Off | Off, Report, Enforce | Policy | Policy manager, company admin, platform admin | controls.work_items.level (off, record, required) |
| Look for keys in | Where keys are searched. Shown when the mode is not Off | Commit messages, Title, Description | Any of Commit messages, Title, Description, Branch name. With none checked, the default three are used | Policy | Same | controls.work_items.sources (commits, title, description, branch) |
| Allowed statuses | The tracker statuses a referenced work item must be in. A status matches by its name (ignoring case) or by its tracker ID. Shown in Enforce mode | Empty: any status | Status names or IDs | Policy | Same | controls.work_items.required_statuses |
| Reuse limit | How many merged merge requests one work item may cover. Shown in Enforce mode | Empty: no limit | A whole number, 0 or more (0: no limit) | Policy | Same | controls.work_items.max_usage |
How keys are recognised is set on the tracker connection, not the policy: Work item projects (only keys of these projects count) and Key pattern (a custom regular expression). See Jira and Built-in tracker.
How keys are found
- The text of the chosen sources is searched for keys. By default a key looks like
PAY-123; case does not matter (feature/pay-123findsPAY-123) and keys are stored in upper case. - Without Work item projects on the tracker connection, only keys of projects that exist in the tracker count, so text such as
SHA-256orUTF-8is not taken for a work item. With Jira, if the list of projects cannot be read, the check waits and is tried again. With the built-in tracker, keys of the company's tracker projects count. - Keys of the tracker project where change approvals are created never count as work items: a change approval is not a business task.
- The merge request must use a tracker. Without one, Report mode is skipped ("No issue tracker is configured for this project.") and Enforce mode fails ("No issue tracker is configured for this project, so work items cannot be checked.").
What Enforce checks
For each work item found, Merge Pilot asks the tracker:
| Check | Fails with |
|---|---|
| A key is referenced at all | "No work item is referenced in the commit messages, title or description." (the sources the policy names) |
| The work item exists | "PAY-123 does not exist" |
| It is in an allowed status (when Allowed statuses is set) | "PAY-123: status is "Done" (expected: In Progress / Ready)" |
| It is under the reuse limit (when Reuse limit is set) | "PAY-123 is already used by 3 merge request(s) (limit 3)" |
All problems are listed together. If the tracker cannot be reached, the control stays pending ("The issue tracker could not be reached (…); retrying.") instead of failing.
The reuse limit
- Only merged merge requests of the company that referenced the work item count, since its last reset. Open merge requests do not count, so two changes in flight for the same task never block each other.
- When this merge request would be the last one the limit allows, Merge Pilot posts a comment on it, Merge Pilot: Business Task Usage Warning, naming the work items and how many uses remain.
- A company admin (or platform admin) can restart a work item's count: on the merge request page, the Issue tracker card shows Reset usage of PAY-123 next to a "already used" problem. Merged merge requests before the reset no longer count, and an open merge request is checked again at once. API:
POST /api/v1/merge-requests/{id}/work-items/{key}/reset-usage. Recorded aswork_item_usage_reset.
When it runs
Work items are looked up each time Merge Pilot processes the merge request: when it is opened, reopened or updated in the VCS, when the policy changes, on Resync on the merge request page, and on the periodic re-check of open merge requests. The result belongs to the head commit; until it is known for the latest commit the control shows "Looking up work items." There is no separate re-scan.
On both GitLab and GitHub, editing the title or description of a merge request starts a new look-up, so a key added there is found at once.
When it fails
The policy's Lifecycle tab decides what a failed work item check does (setting Missing work items or a rejected change approval, API on_fail):
- Block until fixed (
block, the default): the merge request stays open and cannot merge; it is checked again on every change. - Close the merge request (
close): Merge Pilot closes it with a comment naming the policy and the reason; the author has to open a new one. Only a definite failure closes: a missing tracker or an unreachable one never does.
What the merge request shows
- Policy card: the control's line, for example "Linked: PAY-123, PAY-140." or the problems.
- Issue tracker card: the Work items as links to the tracker, the problems in red, and the reset button for admins.
- The status comment in the VCS lists the control with the same text.
- In Jira, the change approval is linked to its work items; their fields can be copied into the change approval (see Jira).
GitLab and GitHub
The checks are the same on both. GitHub pages say pull request. On both, a new look-up starts with new commits, a changed target branch and an edited title or description, among other updates.
Audit
| Action | When |
|---|---|
mr_validated | Enforce mode: the merge request's work items were found and passed every check |
work_item_usage_reset | An admin reset a work item's usage count |
mr_rejected | The policy closed the merge request (Close the merge request) |
mr_gate_approved, mr_gate_pending, mr_gate_blocked | The merge gate changed |
See Audit log.
API
- Policy:
controls.work_itemswithlevel,sources,required_statuses,max_usage(see Change policies). - Merge request (
GET /api/v1/merge-requests/{id}):issue_tracker.work_items(each withkeyandurl),issue_tracker.work_item_problems, and the control's result indecision.controls(control: "work_items",status,blocking,reason).
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →