Workflow and project settings
Each tracker project has its own workflow: its states, the moves people may make between them and, for change approvals, which states approve or reject a change. A company admin shapes it on the project's settings page; Merge Pilot then turns moves into the right states into decisions on merge requests. Using the board and the issue page is described in Board and list and Issue page.
The default workflows
A new project starts with the workflow of its mode (see Two kinds of project):
| VCS mode (change approvals) | Manual mode (tasks) | |
|---|---|---|
| States (category) | Open (To do), In Progress (In progress), Approved (Done), Done (Done), Rejected (Done) | Open (To do), In Progress (In progress), Done (Done) |
| Allowed moves | Open → In Progress, Approved, Rejected; In Progress → Approved, Rejected; Approved → Done | Open → In Progress, Done; In Progress → Done |
| Approve MR states | Approved, Done | None |
| Reject MR states | Rejected | None |
| Issue types (default) | Change approval (default), Task, Bug | Task (default), Bug, Feature |
| Custom fields | Code Reviewer (User), Tester (User), and six check boxes (Boolean) required before entering Approved: Is Code DB-review completed?, Is Code Flow-review completed?, Is Code Load-review completed?, Is Code Log-review completed?, Is Code Quality-review completed?, Is Code Security-review completed?. None when the project is created with Start without the review fields | None |
So, by default, a change approval moves from Open (optionally through In Progress) to Approved once the six reviews are ticked, or to Rejected; after approval it can go on to Done.
The Project settings page
Gear icon Project settings on the board, for company admins and platform admins. Changes are kept only when Save changes is selected (Project settings saved); Cancel leaves without saving. Save changes is unavailable while the name is empty or the project has no state. Every setting below is set on the tracker project, changed by a company admin or platform admin, and saved with PUT /api/v1/mptracker/projects/{id} (written as tracker_project_updated with what changed).
General
| Setting (label in the UI) | What it does | Default | Allowed values | API field |
|---|---|---|---|---|
| Name | The project's name in the picker | From creation | Any text, not empty | name |
| Description | A note about the project | From creation | Any text | description |
| Prefix: | The start of every issue key. Shown, (immutable) | From creation | Cannot be changed | prefix (read only) |
| Mode: | VCS or manual. Shown, (immutable) | From creation | Cannot be changed | mode (read only) |
States
Define workflow states and their categories. One row per state, in board order:
| Setting (label in the UI) | What it does | Default | Allowed values | API field |
|---|---|---|---|---|
| Order (Move NAME up / Move NAME down) | The column order on the board. The first state is where new issues and new change approvals start (through the API: the state with the lowest order) | See The default workflows | Any order | states[].order |
| Colour (NAME colour) | The state's colour on cards, badges and columns | Per state | One of 12 colours | states[].color |
| Category (NAME category) | To do, In progress or Done. On the board, columns of Done states show only issues changed in the last 24 hours; the dashboard counts issues by category | Per state | todo, in_progress, done | states[].category |
| Remove NAME | Removes the state, and with it its moves and its approving or rejecting role. Saving fails while issues are in that state, or while a custom field still names it in its states |
Add state adds one at the end, with New state name, New state colour and New state category (To do by default). A name already in the project is not added. Names cannot be edited on the page; through the API, rename_from ({"old": "new"}) renames a state and moves its issues, approving and rejecting roles and moves along with it.
Allowed transitions
Define which state can transition to which. Click cells to toggle. A table with a row per From state and a column per To state; a ticked cell allows people to move an issue from that state to that one. A state with no ticked cell is a dead end for people. API: allowed_transitions ({"Open": ["In Progress", "Approved"], …}).
These moves bind people only. Merge Pilot's own moves of change approvals go to any state of the project (see Merge Pilot's own moves).
Terminal states
Shown for VCS-mode projects only. Closing states count as an approving vote. Rejection states count as a rejecting vote; the policy then holds or closes the MR. One row per state with two check boxes:
| Setting (label in the UI) | What it does | Default | Allowed values | API field |
|---|---|---|---|---|
| Approve MR | A person moving a change approval into this state approves the change | Approved, Done | Any states that do not reject | closing_states |
| Reject MR | A person moving a change approval into this state rejects the change | Rejected | Any states that do not approve | rejection_states |
A state approves or rejects, never both: while one box of a state is ticked, the other is locked (A state either approves or rejects, never both: untick one to tick the other.). A state ticked both ways cannot be saved (STATE is ticked to both approve and reject: untick one of them.), and the API refuses it too (state "X" cannot be both an approving and a rejecting state).
When a change approval is decided in Merge Pilot (votes on the merge request), Merge Pilot moves it to the first state in the Approve MR list (closing_states[0]), or the first in the Reject MR list. With the defaults that is Approved or Rejected.
The other states a change approval needs (where it goes back for the next approver or after new commits, where it goes on merge and on close) are not set here but in the tracker connection's settings: Reopen status, Merged status, Cancelled status and Transition paths (see Built-in tracker). They name states of this project.
Issue types
Click a type to set it as default. Default type is used for auto-created change approvals.
| Setting (label in the UI) | What it does | Default | Allowed values | API field |
|---|---|---|---|---|
| Types | The types an issue may have. Remove TYPE removes one; New issue type and Add issue type add one | See The default workflows | Any names, each once | issue_types |
| Default type ((default)) | Preselected in Create issue. Change approvals get the tracker settings' Issue type when the project has it, else this default | Change approval (VCS), Task (manual) | One of the types | default_issue_type |
Custom fields
Define custom fields for issues. Removing a field hides it from the UI but preserves existing data. Each field shows its label, its type, its key and badges for its rules (required, req at: STATES, immutable, settable at: STATES), with Move LABEL up / down and Remove LABEL. Add field opens:
| Setting (label in the UI) | What it does | Default | Allowed values | API field |
|---|---|---|---|---|
| Field label (Label (e.g. Priority)) | The name shown on the issue page | none, required | Any text | custom_fields[].label |
| Field key (Key (auto)) | The field's name in the API and in the tracker settings' Custom fields and Field mappings. Filled from the label | From the label: lower case, spaces as _ | Lower-case letters, digits and _; unique in the project | custom_fields[].key |
| Field type | Text, Select, Number, Date, User, Users (multi), Boolean | Text | text, select, number, date, user, user_multi, boolean | custom_fields[].type |
| Field options | The choices of a Select field, comma-separated (Options (comma-separated, e.g. Low, Medium, High)) | None | Any texts | custom_fields[].options |
| Required at creation | Must be filled when a person creates an issue (a Boolean must be on in the dialog). Later changes are checked for the fields they change only: this field cannot be emptied, and other fields can be changed whatever its value | Off | On, off | custom_fields[].required |
| Set once (immutable) | Once it has a value, it cannot be changed | Off | On, off | custom_fields[].immutable |
| Required before entering states: | A person may move an issue into these states only when the field is filled (a Boolean only when it is on); the Required fields dialog asks for it | None | States of the project | custom_fields[].required_at_states |
| Only settable during transitions to: | The value can be changed only together with a move into these states (in the Required fields dialog, or with the API's transition), never by editing the issue nor when creating it (Create issue does not offer it) | None | States of the project | custom_fields[].settable_at_states |
Add adds the field. A field cannot be both Required at creation and Only settable during transitions to: (it could never be given): saving is refused. A value that does not fit the field's type, a choice not among a Select field's options, or a field the project does not define is refused when an issue is saved.
For change approvals, Merge Pilot fills custom fields from the tracker settings' Custom fields and Field mappings when it opens them; a User field gets the company user with that user name, and a Boolean field nobody fills starts off.
Danger zone
Archiving hides the project from the board. Existing issues are preserved but no new issues can be created. Type the prefix (Type PREFIX to confirm) and select Archive project. See Archived projects.
Moves people may make
A person (anyone but an auditor) may move an issue from its state to a state the Allowed transitions tick, by dragging its card or with Move to on the issue page. Before the move:
- the target must be allowed from the current state (transition from "A" to "B" is not allowed (valid: …); from a state with no moves: no transitions allowed from state "A");
- for a change approval, a move into an Approve MR or Reject MR state, or a change to a review attestation given with the move, must be made by the right person (below);
- the fields Required before entering that state must be filled (custom field "LABEL" is required before transitioning to "B");
- fields given with the move must fit their type and their Set once and Only settable during transitions to rules.
The move is recorded in the issue's state history (Time in states), with a system comment and tracker_issue_transitioned.
Who decides a change approval
In a VCS-mode project, a move of a change approval into an Approve MR or Reject MR state is a decision on a merge request, so it is refused (with not allowed to decide this change approval: …) unless:
| Rule | Refused with |
|---|---|
| The person is the change approval's assignee | only the assignee can transition to "STATE" |
| The person has linked their account on the merge request's VCS in My profile, so Merge Pilot can tell them from the author | link your account on the merge request's VCS in My profile before deciding its change approval |
| The person is not the merge request's author | the MR author cannot transition to "STATE" on their own change approval |
An admin is held to the same rules.
The same rules govern a change approval's review attestations: custom fields required before entering an Approve MR or Reject MR state, such as the six review check boxes of a new project. Ticking one vouches for a review the decision rests on, so only the person who may decide the change approval may change it, on the issue page, with a move or through the API (only the assignee can set "LABEL", the MR author cannot set "LABEL" on their own change approval). Who the assignee is follows the policy's assignment (see Assignment); someone who may approve and is not the assignee can take the change approval over on the merge request page (see Taking a change approval) or vote there instead.
Passing these rules makes the move happen; whether it counts is decided next by the change policy (below).
What Merge Pilot does on each move
For a change approval (an issue Merge Pilot opened for a merge request):
| Move by a person | What Merge Pilot does |
|---|---|
| Into an Approve MR state | Counts it as the assignee's approval, under the policy's rules (who may approve, how many approvals, separation of duties). When the approvals are met, the change approval is approved and the merge gate updated. When more are needed, the approval is recorded and Merge Pilot moves the change approval back to the Reopen status for the next approver. A decision that does not count is undone: the change approval goes back for a decision |
| Into a Reject MR state | Counts it as a rejection under the policy's When rejections reject (see Rejections). With the default, One rejection rejects, the change approval is rejected and the policy holds or closes the merge request. When the policy needs more rejections, the rejection is recorded and Merge Pilot moves the change approval back to the Reopen status so others can still decide it, or back to its approving state when its approvals still meet the policy. This holds from an Approve MR state too, when the workflow allows that move: a rejection that rejects withdraws the approval. A rejection that does not count (under the rules of Decisions made in the tracker) is undone: an approved change approval goes back to its approving state and the approval stands; an open one goes back for a decision |
| Out of an Approve MR state into a state that neither approves nor rejects | Withdraws the approval, which is a decision too: it counts only when made by someone who may decide the change approval (an approver of the change under its policy, never the merge request's author) or by a company or platform admin. Then an approved change approval is open again and needs a fresh quorum; after the merge, the merge request is flagged instead. Anyone else's move is undone: Merge Pilot moves the change approval back to its approving state, comments on it and on the merge request, and writes change_approval_vote_ineligible; the approval stands |
| Any other move | Nothing beyond the record of the move |
Once Merge Pilot has the change approval as approved or rejected, a later move into an approving or rejecting state does not change that decision (for example Approved → Done with the default workflow).
When Merge Pilot cannot take a decision up at once, the move is kept and the person who made it is told the issue moved to "STATE" but the merge request could not be updated; move it out and back to "STATE" to retry.
How decisions count, what is ignored and what is written to the audit log is on Decisions made in the tracker and Change approval lifecycle.
Issues of manual-mode projects are not tied to merge requests: their moves are only recorded.
Merge Pilot's own moves
Merge Pilot moves a change approval itself:
- back to the Reopen status when another approval is needed, after new commits (when the policy reopens it), when a decision did not count, or when a rejection was recorded but the policy needs more;
- back to the first Approve MR state when an approved change approval was moved out of it by a withdrawal or rejection that did not count, or by a rejection that leaves it approved under the policy;
- to the Merged status when the merge request merges (once approved: an emergency change's review still owed moves there when it is approved) and to the Cancelled status when it closes or is superseded, when these are set;
- to the first Approve MR or Reject MR state when the change approval is decided by votes in Merge Pilot;
- through the states of a Transition path on the way, when one is set for the target.
These moves:
- may go to any state of the project, whatever Allowed transitions say, and need no required fields;
- match the state name ignoring case; a name the project does not have fails (state "X" does not exist in project PREFIX), and the merge request page shows it (see Tracker moves that fail);
- never count as decisions;
- are recorded in Time in states with State changed from A to B by Merge Pilot.
Changing a workflow in use
- Changes apply from the next move: existing issues keep their state.
- A state cannot be removed while issues are in it: cannot delete state "X": N issues exist in this state. Move them first.
- Every state named in Allowed transitions, Terminal states or a custom field's states must exist. The page removes a removed state from Allowed transitions and Terminal states, but not from custom fields: saving then fails (custom field "LABEL" references unknown state "X" in required_at_states) until the field is removed. In a new VCS-mode project, removing Approved therefore needs the six review check boxes removed too.
- The tracker connection's Reopen status, Merged status, Cancelled status and Transition paths name states too. After removing or renaming such a state, update the connection's settings, or Merge Pilot's moves to it fail.
- Removing the Approve MR (or Reject MR) tick from every state leaves change approvals that nobody can approve (or reject) in the tracker.
- An archived project cannot be changed (cannot update archived project).
Archived projects
Archiving (Archive project in the Danger zone, DELETE /api/v1/mptracker/projects/{id}, written as tracker_project_archived):
- hides the project from the board's picker; its issues are kept;
- makes its issues read-only for people: moves, edits, assignments, comments and new issues are refused (the project is archived: its issues are read-only). Create issue is refused, and a built-in tracker connection or repository that still names the project cannot open change approvals in it (cannot create issue: tracker project "PREFIX" is archived; see When creation fails);
- does not stop Merge Pilot's own moves and comments on change approvals opened in it before, so they stay in step with their merge requests; such a change approval can still be decided by votes in Merge Pilot;
- stops its keys from counting as work items, unless the tracker settings' Work item projects name it;
- cannot be undone, and the prefix stays taken.
The Archived projects page (archive icon on the board, for admins) lists them: Archived projects are read-only. It has a Project picker, Search issues... (summary), Filter by state and N issues, and a table with Key, Summary, Type, State, Assignee and Updated, 25 per page. With none: No archived projects (Archived tracker projects will appear here.). Back to tracker returns to the board.
API
GET /api/v1/mptracker/projects/{id}:name,prefix,description,mode,states[](name,category,order,color),allowed_transitions,closing_states,rejection_states,issue_types,default_issue_type,custom_fields[],archived.PUT /api/v1/mptracker/projects/{id}: any of the fields above exceptprefix,modeandarchived, plusrename_from. Fields left out are kept.DELETE /api/v1/mptracker/projects/{id}: archive.
Related pages
- Tracker, Board and list, Issue page.
- Built-in tracker: the connection's statuses and transition paths.
- Approval and Approving and rejecting.
Video tutorials
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →