Skip to main content
2 video tutorials

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 movesOpen → In Progress, Approved, Rejected; In Progress → Approved, Rejected; Approved → DoneOpen → In Progress, Done; In Progress → Done
Approve MR statesApproved, DoneNone
Reject MR statesRejectedNone
Issue types (default)Change approval (default), Task, BugTask (default), Bug, Feature
Custom fieldsCode 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 fieldsNone

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 doesDefaultAllowed valuesAPI field
NameThe project's name in the pickerFrom creationAny text, not emptyname
DescriptionA note about the projectFrom creationAny textdescription
Prefix:The start of every issue key. Shown, (immutable)From creationCannot be changedprefix (read only)
Mode:VCS or manual. Shown, (immutable)From creationCannot be changedmode (read only)

States​

Define workflow states and their categories. One row per state, in board order:

Setting (label in the UI)What it doesDefaultAllowed valuesAPI 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 workflowsAny orderstates[].order
Colour (NAME colour)The state's colour on cards, badges and columnsPer stateOne of 12 coloursstates[].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 categoryPer statetodo, in_progress, donestates[].category
Remove NAMERemoves 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 doesDefaultAllowed valuesAPI field
Approve MRA person moving a change approval into this state approves the changeApproved, DoneAny states that do not rejectclosing_states
Reject MRA person moving a change approval into this state rejects the changeRejectedAny states that do not approverejection_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 doesDefaultAllowed valuesAPI field
TypesThe types an issue may have. Remove TYPE removes one; New issue type and Add issue type add oneSee The default workflowsAny names, each onceissue_types
Default type ((default))Preselected in Create issue. Change approvals get the tracker settings' Issue type when the project has it, else this defaultChange approval (VCS), Task (manual)One of the typesdefault_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 doesDefaultAllowed valuesAPI field
Field label (Label (e.g. Priority))The name shown on the issue pagenone, requiredAny textcustom_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 labelFrom the label: lower case, spaces as _Lower-case letters, digits and _; unique in the projectcustom_fields[].key
Field typeText, Select, Number, Date, User, Users (multi), BooleanTexttext, select, number, date, user, user_multi, booleancustom_fields[].type
Field optionsThe choices of a Select field, comma-separated (Options (comma-separated, e.g. Low, Medium, High))NoneAny textscustom_fields[].options
Required at creationMust 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 valueOffOn, offcustom_fields[].required
Set once (immutable)Once it has a value, it cannot be changedOffOn, offcustom_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 itNoneStates of the projectcustom_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)NoneStates of the projectcustom_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:

  1. 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");
  2. 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);
  3. the fields Required before entering that state must be filled (custom field "LABEL" is required before transitioning to "B");
  4. 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:

RuleRefused with
The person is the change approval's assigneeonly 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 authorlink your account on the merge request's VCS in My profile before deciding its change approval
The person is not the merge request's authorthe 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 personWhat Merge Pilot does
Into an Approve MR stateCounts 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 stateCounts 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 rejectsWithdraws 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 moveNothing 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 except prefix, mode and archived, plus rename_from. Fields left out are kept.
  • DELETE /api/v1/mptracker/projects/{id}: archive.

Video tutorials

Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →

A Required Field Before ApprovalYouTube ↗
Shape the Tracker Workflow — States and MovesYouTube ↗