Human in the loop

Overview

By default, a mission runs to the end and then waits at a pull request for a person to accept it. That is the only gate, and it is at the end.

Checkpoints let you add more gates. If you set a checkpoint on a role, the pipeline holds when that role finishes, before the next stage starts. You can then read what the role produced and decide if the mission continues from that result.

Where a run can hold

The Builder checkpoint holds after CI, not immediately after the push. So the commits go out and your CI pipeline runs as usual. Only the move to review waits for you.

QA cannot be a checkpoint. QA is the last stage, and the pull request at the end is already the gate after it. SHIP parses qa.checkpoint but ignores it, and shows a warning on the mission.

A checkpoint holds a mission only when the mission would move forward. If a stage fails, or the Reviewer asks for changes, the mission goes back to the Builder as usual.

Enable checkpoints

version: 1

agents:
  planner:
    checkpoint: true
  reviewer:
    checkpoint: true

deployments:
  preview:
    # ...

This configuration applies to every mission in the project. To set the same field for one mission only, use PUT /v1/missions/{issueId}/agents-override. The override merges per role and per field, so a Reviewer checkpoint on one mission does not change the Planner setting in ship.yml.

Auto-merge works in the opposite direction. If you enable it for a project or for a mission, a mission that passes review and QA merges its own pull request. Auto-merge is off unless you turn it on.

Answering a hold

When a mission holds, it says so on the issue and on its console page, and it names the role that stopped it.

A hold stops only the next dispatch. The stage that just finished is complete: SHIP recorded its result, and its sandbox no longer exists. When you release the hold, SHIP sends the held dispatch. The mission continues from where it stopped and does not do any work again. SHIP holds only one dispatch at a time, so checkpoints on two roles work. The mission holds at the first, continues, and holds again at the second.

You can reply in two ways:

• Resume the mission from the console, with @SHIP resume on the issue, or with POST /v1/missions/{issueId}/resume. The mission then continues.
• Send changes instead. An instruction about the output of the held stage runs that stage again with your feedback. If you do not agree with a plan, the Planner plans again, and the Builder does not build the old plan.

Compared with the board, a checkpoint has this advantage: the mission stops at the point where a change of mind costs the least.

Answer a hold soon. A hold is a pause in a mission that is still active. It is not a place to keep work until next week.

Pausing and stopping by hand

The same controls work on all missions, with or without a checkpoint. Use them from the issue, the console or the API.

Stop does not reject the work. It does not change the branch or the pull request, so it is safe to stop a mission that you do not want any more. The usual way to continue later is to start a new mission on the same issue.

An instruction that you send to an active mission has priority over the automated guards. If a mission is about to stop because it fails the same way again and again, your instruction clears that history. The loop then continues with your instruction. For the same reason, if you have feedback, send an instruction and do not restart the mission. A restart checks an unchanged pull request against results that it already has, and correctly does nothing.

Related

• Retry limits set how long a mission works on a problem before it stops and asks for you.
• Agent prompts change how a role behaves. This is often the better fix if you reject the same thing at the same checkpoint again and again.
• The schema reference lists checkpoint with all the other ship.yml fields.