Skip to main content

Ship and follow: watch a push to completion

A push starts a chain — CI run, required check, auto-merge, and, when configured, deploy — and an agent should not have to poll four surfaces to see it land. slipstream_follow watches the whole chain in one call: it waits by default, streams each milestone as it happens, and returns a per-hop timeline when the push is live or intentionally complete after CI — or returns immediately the moment anything fails.

Legend: green = engine-owned hops · blue = GitHub-side · red = failure path with concrete next steps.

The three calls​

  1. Prewarm. Before pushing, slipstream_prewarm wakes an executor for your repo so a hot machine with warm caches is waiting when the webhook lands. Optional, but it removes the last cold-start from the path. It answers inside a sub-second budget and never waits for the wake to finish; passing the head sha additionally requests an install-warm, reported as prepare_state (pending / skipped) — never as a completed one. On a not-yet-pushed sha the install-warm has never run to completion, so it is skipped rather than lost; pre-seeding a cold machine's clone without a pushed sha is a known follow-up.
  2. Push. A normal git push. GitHub delivers the webhook and the run starts as described in push to green.
  3. Follow. slipstream_follow attaches to that push and waits — streaming each phase change and stage transition as an MCP progress notification, so the agent narrates the pipeline in real time instead of polling. When the chain reaches its terminal state, the call returns a per-hop timeline (how long intake, run, merge, and deploy each took) plus waited_s.

The terminal phase for a merge to main with ship-on-green enabled is live: the deploy ran and the service answered its health check. A repository proven to have no deploy contract terminates successfully at ci_only after green merge-commit CI; it is not described as deployed or live. An unreadable, invalid, or required deploy recipe never becomes ci_only.

When something fails​

Follow never makes you wait out the clock on a red run: the call returns as soon as any hop fails, naming the failing hop with concrete next steps. From there the agent stays in the same session — get a diagnosis of the failing stage, tail the log, re-run, or test a fix in a sandbox. All of it goes through the MCP server.

Async mode​

slipstream_follow blocks by default, up to the server's 45-second inline cap (larger wait_s values are accepted but capped, so the handle always returns before an ordinary client timeout). If the journey outlives that wait, resume it with slipstream_task_get and a wait_s: it waits on that same task for the next milestone exactly as follow does, and loops until done — a blocking resume, not a polling cadence. Re-calling slipstream_follow with the same repo and sha resumes the same task and its cumulative timeline too, but hosts that render the ship card draw a new one for every follow call, so keep that for re-rendering the card (after a rerun, say) or for a caller that lost its task_id. Pass wait_s: 0 for async mode: the call returns a task_id immediately, and the agent can read it with slipstream_task_get (instant, non-blocking when wait_s is omitted) or subscribe to the push-status resource slipstream://push/{owner}/{repo}/{sha} to be notified instead of holding a connection open.