How a run executes, from intake to pull request

The full lifecycle, in the order it happens, with the architectural detail platform engineers ask for first. You should not have to read the documentation to understand where code executes and what leaves your network.

Lifecycle Architecture Runtime workers Worked example

The execution lifecycle

Twelve stages. A run can stop, wait for a person, or fail at any of them without losing the task or the evidence produced so far.

01
Task creation or issue import
Person or issue provider
The objective arrives from a person or is imported from GitHub, Linear or Jira. The upstream system stays authoritative for its own status.
02
Requirements clarification
Planner session and person
The planner turns the objective into numbered requirements and states its assumptions. Anything ambiguous is asked, not guessed.
03
Workflow selection
Control plane
A workflow decides which roles participate, which tools they may use, which checks must pass and where approval is required.
04
Worker reservation
Scheduler
The run reserves a concurrency slot on a worker matching the required labels, and holds it for the life of the run.
05
Worktree and workspace creation
Runtime worker
A Git worktree is created from the worker’s local mirror, then the Docker Compose environment for the repository starts, including a preview service when the task needs one.
06
Plan and sub-agent delegation
Primary agent session
The primary session publishes a plan of steps mapped to requirements and delegates steps to specialist sessions, each with its own permissions.
07
Tool and MCP activity
Agent sessions
Sessions read and write files, run commands and call MCP tools inside the workspace. Destructive tool use can require approval before it runs.
08
Human intervention
Person
A reply in the task redirects the run. Pausing holds the slot; cancelling can keep the workspace for inspection.
09
Tests and preview
Runtime worker
Unit tests, type checks and preview smoke tests run in the workspace. Each result attaches to the requirement it addresses.
10
Oversight review and merge workspace
Reviewer and oversight sessions
Parallel work is integrated in a controlled merge workspace. An independent reviewer reads the combined diff against the requirements ledger.
11
Approval and pull-request creation
Person, then control plane
A named person approves the handoff with the evidence in view. BranchRunner pushes the branch and opens the pull request.
12
Completion, retention or cleanup
Control plane
The run closes with its evidence and audit record. Workspaces are retained or removed on policy; failed runs are kept for inspection.

System architecture

Three planes. The control plane decides and records. Runtime workers execute. External providers are reached deliberately, per run, under credentials you supply.

Control plane

Task and requirements store

Run scheduler and worker registry

Workflow and policy engine

Approvals and budgets

Audit log and evidence store

Web application and API

No agent process and no repository checkout lives here.

Runtime worker

Worker agent and job runner

Local repository mirror

Git worktrees, one per session

Docker Compose workspace

Coding agent processes

Egress allowlist and secret injection

Add workers to add capacity. Workers can sit in your network.

External

Git providerFetch, push, pull requests

Issue providerImport and status updates

Model providersPer session, your credentials

MCP serversScoped per role and workflow

Notification targetsWebhooks, chat, email

Agents never run on the control plane

Coding agents execute inside the workspace on a worker. The control plane holds state and decisions.

Parallel work, separate worktrees

Concurrent sessions get their own worktree when required, so they cannot overwrite each other.

Oversight before the branch

An oversight stage integrates parallel work in a controlled merge workspace before it moves toward the main development branch.

Mirror first, credentials second

New worktrees come from the worker's local mirror. Git credentials are needed only for remote fetch, push and pull-request operations.

Runtime workers and scheduling

A worker is a machine with Docker and the BranchRunner worker agent. It registers with the control plane, advertises labels and capacity, and receives run reservations.

Requirements

Docker, disk for mirrors and workspaces, outbound access to the control plane

Registration

A join token from the control plane. Workers can be added and drained at any time.

Labels

region · gpu · network-zone · repo-mirror

Scheduling

By label match, then free concurrency slots, then least loaded

Reservation

A run holds a slot for its whole life, including waiting for approval

Cleanup

Workspaces are removed on the retention policy; failed runs are kept for inspection

Kubernetes is not required. If you already run a cluster, workers can live on it as ordinary workloads.

Add a workershell

docker run -d --name branchrunner-worker \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v branchrunner-mirrors:/var/lib/branchrunner \
  -e BR_CONTROL_PLANE=https://branchrunner.internal \
  -e BR_JOIN_TOKEN=$BR_JOIN_TOKEN \
  -e BR_LABELS=region=eu-west,network-zone=private \
  ghcr.io/branchrunner/worker:1.0

Workers3 online

worker-1eu-west3 / 4Busy

worker-2eu-west2 / 4Busy

worker-3on-premise0 / 2Idle

One concrete run

Read this as a use case

TASK-482, second attempt, in an example repository. Timestamps are from the run's audit record.

Run 18 · TASK-482worker-2env-br-482-aruns/br-482Completed · PR #1284

14:00:02IntakeImported from Linear LIN-482. Task created with 5 requirements after clarification.

14:00:41ReservationSlot 3 of 4 reserved on worker-2 (region=eu-west).

14:01:10WorkspaceWorktree runs/br-482 created from local mirror. Compose environment env-br-482-a started: api, worker, postgres, preview.

14:01:58PlanPlanner published 5 steps mapped to R1–R5. Two specialist sessions requested.

14:03:06ImplementationImplementer edited src/workers/webhook.ts (+41 −7) in worktree a. Alerting session worked in worktree b.

14:04:01AttentionApproval requested for docker compose down -v. Declined by fictional reviewer; session restarted the preview container instead.

14:07:22ValidationUnit tests 212 passed. Type check clean. Preview smoke test passed on env-br-482-a.

14:19:40OversightWorktrees a and b integrated in the merge workspace. No conflicts.

14:24:12ReviewIndependent reviewer session confirmed R1–R5 against the diff. No changes requested.

14:31:12ApprovalHandoff approved with evidence attached.

14:31:14DeliveryBranch pushed. Draft pull request #1284 opened into main.

14:31:20CompletionRun completed. Workspace retained for 7 days. 41 audit events recorded.

Total 31m 18s · $4.20 · 128.4k tokens · 41 audit eventsRead this as a use case

When a run does not succeed

A failure is an outcome with evidence, not a dead end. The task survives, the workspace can be kept, and the next attempt starts from what the last one produced.

FailedEnvironment never became healthy

The preview could not start because port 3000 never became healthy. The workspace and container logs were preserved. Review the health check or retry with the current environment.

Needs attentionApproval required to continue

A session asked to run a destructive command. The run holds its worker slot and waits. Declining records the decision and the agent's next action.

StoppedHard budget limit reached

Spend hit the hard limit. The run ended, the diff and evidence so far were retained, and the owner was notified with the remaining requirements.

Changes requestedReview rejected the handoff

The reviewing session found an unsatisfied requirement. The run returns to implementation with the finding attached, without losing the plan.

Read it, or run it

The architecture is documented in full, and the Community edition is the same platform described on this page.

Read the documentation Review Community requirements