Skip to main content
Video tutorial · 2:14

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 valueWhat it doesEffect on the merge gate
OffoffWork items are not looked forNone
ReportrecordThe keys found are recorded and linked to the change approval; they are not checked in the trackerNone: the control always passes ("Linked: PAY-123." or "No work items referenced (recorded only).")
EnforcerequiredAt least one work item must be referenced, must exist in the tracker and, when set, be in an allowed status and under the reuse limitWaiting 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 doesDefaultAllowed valuesSet whereWho can change itAPI field
Mode (row Work items)See ModesOffOff, Report, EnforcePolicyPolicy manager, company admin, platform admincontrols.work_items.level (off, record, required)
Look for keys inWhere keys are searched. Shown when the mode is not OffCommit messages, Title, DescriptionAny of Commit messages, Title, Description, Branch name. With none checked, the default three are usedPolicySamecontrols.work_items.sources (commits, title, description, branch)
Allowed statusesThe 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 modeEmpty: any statusStatus names or IDsPolicySamecontrols.work_items.required_statuses
Reuse limitHow many merged merge requests one work item may cover. Shown in Enforce modeEmpty: no limitA whole number, 0 or more (0: no limit)PolicySamecontrols.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-123 finds PAY-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-256 or UTF-8 is 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:

CheckFails 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 as work_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​

ActionWhen
mr_validatedEnforce mode: the merge request's work items were found and passed every check
work_item_usage_resetAn admin reset a work item's usage count
mr_rejectedThe policy closed the merge request (Close the merge request)
mr_gate_approved, mr_gate_pending, mr_gate_blockedThe merge gate changed

See Audit log.

API​

  • Policy: controls.work_items with level, sources, required_statuses, max_usage (see Change policies).
  • Merge request (GET /api/v1/merge-requests/{id}): issue_tracker.work_items (each with key and url), issue_tracker.work_item_problems, and the control's result in decision.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 →

Require a Work Item on Every ChangeYouTube ↗