Human in the loop

Overview

By default a mission runs the whole way and stops at a pull request for a human to accept. That is one gate, at the end.

Checkpoints let you add more. Set one on a role and the pipeline holds as soon as that role finishes, before the next stage starts, so you can read what it produced and decide whether the run should continue on it.

Where a run can hold

The builder's hold sits after CI rather than straight after the push, so the commits go out and your pipeline runs as normal. What waits is the decision to move on to review.

QA cannot be a checkpoint. It is the last stage, and the pull request at the end is already that gate. Setting qa.checkpoint parses but is dropped, with a warning on the mission.

A checkpoint only holds a run that was going to move forward anyway. A failed stage, or a reviewer asking for changes, takes the usual path back to the builder instead.

Enable checkpoints

version: 1

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

deployments:
  preview:
    # ...

That applies to every mission the project runs. For a single mission, PUT /v1/missions/{issueId}/agents-override sets the same field for that run alone, merging per role and per field, so one mission's reviewer checkpoint leaves the planner's ship.yml setting alone.

Auto-merge is the same dial turned the other way: enable it per project or per mission and a run that satisfies review and QA merges its own pull request. It is off unless you turn it on.

Answering a hold

The mission says it is holding on the ticket and on its console page, naming the role that stopped it.

What it holds is the next dispatch, and only that. The stage that just finished is finished, its result recorded and its sandbox gone. Releasing replays the parked dispatch, so the run picks up where it left off rather than redoing anything. Only one dispatch is ever parked, which is why checkpoints on two roles work: the run holds at the first, continues, and holds again at the second.

You have two replies. Resume from the console, @SHIP resume on the ticket, or POST /v1/missions/{issueId}/resume, and the run carries on. Or send changes instead of resuming: an instruction aimed at what the held stage produced re-runs that stage with your feedback, so a plan you disagree with is re-planned rather than built. That is the reason a checkpoint beats watching the board. The run is stopped at the moment changing your mind is cheapest.

Answer it reasonably promptly. A hold is a pause in a live run, not a parking space for work you will come back to next week.

Pausing and stopping by hand

The same controls work on any mission, checkpoint or not, from the ticket, the console, or the API.

Stop is not a rejection. It leaves the branch and pull request where they are, so stopping a run you no longer want is safe and starting a fresh one on the same issue later is the normal way back.

Anything you send a running mission outranks the automated guards. If a mission is close to giving up because it keeps failing the same way, your instruction clears that history and the loop continues on what you told it. This is also why an instruction beats a restart when you have feedback: a restart re-checks an unchanged pull request against results it already has and correctly does nothing.

Related

• Retry limits decide how long a mission works a problem before it stops and asks for you.
• Agent prompts change how a role behaves, which is often the better fix when you keep rejecting the same thing at the same checkpoint.
• The schema reference lists checkpoint alongside every other ship.yml field.