Skip to content

Runs

A run is a single execution of a Pipemason program.

A run is the unit Pipemason executes end to end: one unit of work becomes one branch and, optionally, one pull request. It is what you get when you point Pipemason at a single feature, and it is also what a program executes once per story.

Start a run

From inside any git repository, describe the work in plain text:

pipemason start "add a /healthz endpoint that returns 200 ok"

On startup the runner:

  • scaffolds a .pipeline/ workspace in your repo if one does not already exist,
  • registers the run with the cloud and prints the run id,
  • creates the working branch and begins the first phase.

What a run produces

A run works on its own branch and walks the phases from analyze through finalize. At finalize it always pushes the branch; opening a pull request is opt-in. The end result is a branch with the change, its tests, and a record of how it got there.

Note

Open a PR automatically by passing --pr at start, or by setting finalize.create_pr in your .pipeline/config.yml. Without either, the run still pushes the branch so you can open the PR yourself.

Watching a run

A run typically takes 5–30 minutes depending on scope. You can watch it two ways:

  • Locally — the runner writes progress to .pipeline/STATE.md and appends a JSON event per iteration to .pipeline/iterations.log. Run pipemason status to print the current state.
  • On the dashboard — the same events stream live to pipemason.com/dashboard, where you can click into a run for its event stream and per-phase progress.

Useful flags

pipemason start "..." --pr             # open a PR at finalize
pipemason start "..." --stash          # auto-stash a dirty working tree
pipemason start "..." --base develop   # override base-branch detection
pipemason status                        # print .pipeline/STATE.md
pipemason resume                        # continue after fixing an escalation

When a run stops

A run does not guess its way past ambiguity. If it hits something it cannot safely resolve — a rebase conflict, a gate it cannot recover from — it escalates: it stops and records what it needs from you in STATE.md. Fix the underlying issue and run pipemason resume to continue from where it left off. The State machine page describes exactly when this happens.

Runs vs. programs

A single run handles one feature. When you need to build or upgrade a whole system, a program decomposes the intent into many stories and drives a run for each one in dependency order. See Programs for that larger scale.