Tracker
The Tracker is the issue tracker built into Merge Pilot. It holds change approvals for companies that do not use Jira, or that want their change approvals kept inside Merge Pilot, and it can hold ordinary tasks that merge requests reference as work items. This section covers using it day to day; connecting it is described in Built-in tracker.
For a short overview of what it is for, see the Built-in tracker feature page.
Where it is
Tracker is in the left menu, in the Work group, for every role. It opens the board of the company's first tracker project (projects are sorted by name); the project picker switches to another. A platform admin works in the company selected in the company switcher.
Pages of the tracker:
| Page | What it shows |
|---|---|
| Board and list | A project's issues as columns by state, or as a table. See Board and list |
| Issue page | One issue: its fields, comments, history and merge request. See Issue page |
| Project settings | A project's states, transitions, approving and rejecting states, issue types and custom fields. Company admins only. See Workflow and project settings |
| Archived projects | Archived projects and their issues, read-only. See Archived projects |
The Dashboard shows a card Active tracker issues: the company's issues in states of the categories To do and In progress, with the number in Done states below it.
Two kinds of project
Every tracker project has a Mode, chosen when it is created and never changed afterwards:
| Mode (label in the UI) | API value | What it is for | Who creates its issues |
|---|---|---|---|
| VCS | vcs | Change approvals. A built-in tracker connection points to a VCS-mode project, and Merge Pilot opens a change approval there for each change that needs one | Merge Pilot only. People cannot create issues in it |
| Manual | manual | Ordinary tasks, which merge requests can reference as work items | People, with Create issue |
| VCS mode | Manual mode | |
|---|---|---|
| Starting states | Open, In Progress, Approved, Done, Rejected | Open, In Progress, Done |
| Starting moves | Open → In Progress, Approved or Rejected; In Progress → Approved or Rejected; Approved → Done | Open → In Progress or Done; In Progress → Done |
| Approving and rejecting states | Approved and Done approve; Rejected rejects | None (not shown in its settings) |
| Starting issue types | Change approval (default), Task, Bug | Task (default), Bug, Feature |
| Starting custom fields | Code Reviewer, Tester and six review check boxes that must be ticked before Approved (see Workflow). Start without the review fields when creating the project leaves them out (API no_custom_fields, or custom_fields for your own); fields can be added later in the project's settings | None, unless the project is created with its own (API custom_fields) |
| Assignee | Set by Merge Pilot; people cannot change it in the tracker | Anyone may assign the issue |
| Summary and description | Written by Merge Pilot from the tracker settings' templates; not edited on the issue page | Edited on the issue page |
A project is created on the tracker page (New project, or Create project when the company has none) or, for a VCS-mode project, from the connection dialog (Create tracker project, see Built-in tracker):
| Field (label in the UI) | Allowed values |
|---|---|
| Project name | Any text, required |
| Prefix | 2 to 10 upper-case letters and digits, starting with a letter (prefix must start with a letter), required, unique within the company (an archived project keeps its prefix). Issue keys are the prefix and a number: CHG-1, CHG-2, … The prefix cannot be changed later |
| Description (optional) | Any text |
| Mode | Manual (selected by default) or VCS |
Custom fields given when a project is created (API custom_fields) are checked as in the project settings: each needs a key and a label, a known type, options for a select field, and a key no other field of the project has (see Custom fields). A project with a field that fails these checks is not created.
Who may do what
| Action | Platform admin | Company admin | Policy manager | Auditor | User |
|---|---|---|---|---|---|
| See projects, boards, issues and comments | Yes | Yes | Yes | Yes | Yes |
| Create tracker projects, change their settings, archive them | Yes | Yes | No | No | No |
| Create issues in manual-mode projects | Yes | Yes | Yes | No | Yes |
| Move issues between states, edit fields, comment | Yes | Yes | Yes | No | Yes |
| Assign issues of manual-mode projects | Yes | Yes | Yes | No | Yes |
| Approve or reject a change approval in the tracker (move it to an approving or rejecting state) | Assignee only | Assignee only | Assignee only | No | Assignee only |
The auditor reads everything and changes nothing (see The auditor is read-only): the issue page shows no Move to buttons, comment box or assignee search to an auditor, its switches cannot be changed, and cards on the board cannot be dragged.
Change approvals in the tracker
When a merge request needs a change approval and the repository's VCS connection is linked to a built-in tracker connection, Merge Pilot opens it as an issue in a VCS-mode project. In short:
- It is created in the project's first state, with the summary, description and fields the tracker settings give, a link to the merge request, and an assignee who may decide it (see Assignment).
- Moving it to an approving state is an approval, to a rejecting state a rejection. Only its assignee may make these moves, never the merge request's author, and only after linking their account on the merge request's VCS in My profile. Merge Pilot then counts the decision under the change policy's rules (see Decisions made in the tracker).
- Moving it out of an approving state withdraws the approval.
- Merge Pilot moves it itself: back for the next approver, to the Reopen status after new commits, to the Merged status or Cancelled status when the merge request merges or closes, and to an approving or rejecting state when the change approval is decided in Merge Pilot.
The details are on Workflow and project settings, and the whole life of a change approval on Change approval lifecycle.
A change approval's link (on the merge request page and in the merge request's comments) opens the board of its tracker project; the issue is opened from there.
Work items
Issues of the company's tracker projects can be referenced from merge requests as work items, when the merge request's tracker is the built-in tracker. Keys of the project where change approvals are created never count. See Tracker issues as work items.
What the tracker does not have
- No attachments.
- No links between issues: a change approval is tied to its merge request, not to other issues.
- Comments cannot be edited or deleted.
- No webhooks and no notifications of its own.
- A project cannot be deleted or brought back from the archive.
API
All tracker endpoints act on the caller's company (a platform admin passes company_id).
| Endpoint | What it does | Who |
|---|---|---|
GET /api/v1/mptracker/projects (include_archived=true adds archived ones) | List projects | Any role |
GET /api/v1/mptracker/projects/{id} | One project with its workflow | Any role |
POST /api/v1/mptracker/projects (name, prefix, mode, description) | Create a project | Company admin, platform admin |
PUT /api/v1/mptracker/projects/{id} | Change a project's settings | Company admin, platform admin |
DELETE /api/v1/mptracker/projects/{id} | Archive a project | Company admin, platform admin |
GET /api/v1/mptracker/projects/{id}/board, GET /api/v1/mptracker/projects/{id}/issues | Board and list (see Board and list) | Any role |
POST /api/v1/mptracker/projects/{id}/issues | Create an issue in a manual-mode project | Any role but auditor |
GET /api/v1/mptracker/issues/{id}, GET /api/v1/mptracker/issues/by-key/{key} | One issue | Any role |
PUT /api/v1/mptracker/issues/{id}, POST /api/v1/mptracker/issues/{id}/transition, POST /api/v1/mptracker/issues/{id}/assign | Edit, move, assign (see Issue page) | Any role but auditor |
GET and POST /api/v1/mptracker/issues/{id}/comments | Read and add comments | Read: any role; add: any role but auditor |
GET /api/v1/mptracker/users?q= | Active users of the company whose user name or display name starts with q (at most 50, 20 by default) | Any role |
Audit log
| Action | When |
|---|---|
tracker_project_created, tracker_project_updated, tracker_project_archived | A project was created, its settings changed (with what changed), or it was archived |
tracker_issue_created | Someone created an issue in a manual-mode project |
tracker_issue_updated | An issue's summary, description, type or custom fields were changed |
tracker_issue_transitioned | Someone moved an issue to another state |
tracker_issue_assigned | Someone assigned an issue of a manual-mode project |
Comments are not written to the audit log; change approvals' own actions are listed on Change approval lifecycle. See also Audit log.
Related pages
- Built-in tracker: the connection and its tracker settings.
- Board and list, Issue page, Workflow and project settings, Tracker issues as work items.
- Change approval lifecycle and Approving and rejecting.
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →