Skip to main content

Workflows, Instances & Runs

Workflow → Workflow Version → Workflow Instance → Stage → Run​

This is the chain every execution flows through:

  • A Workflow is a named family (WF_FEATURE_DELIVERY) belonging to one project. It has a lifecycle: ACTIVE / SUSPENDED / ARCHIVED.
  • Each Workflow has one or more immutable Versions — a BPMN XML definition plus a JSON config (which agent profile runs which BPMN service task, plus artifact/approval policy). Exactly one version is PUBLISHED and deployed to Camunda at a time; publishing a new version supersedes the old one.
  • A Workflow Instance is one running execution of a published version — created with a free-form input JSON (the actual task: objective, acceptance criteria, which repository role to use), then started.
  • Camunda drives the instance through the BPMN graph. Each service task it reaches becomes a Stage (an audit-trail row) containing one or more Runs.
  • A Run is one real agent execution: it resolves the task's Agent Profile, builds a RunSpec (merged permissions, mounted skills/hooks/knowledge, resolved secrets, git branch), and dispatches it to a Worker.

How a BPMN task picks its Agent Profile​

Three ways, in priority order:

  1. serviceTaskAgents in the workflow version's config JSON — {"task_implement_feature": {"agentProfileKey": "profile-engineer"}}. This is the normal, recommended path — it lets the same BPMN diagram be reused across stack-specific workflow variants (e.g. profile-java-dev vs profile-react-dev) just by changing the config.
  2. A zeebe:taskHeaders header agentProfileKey directly on the BPMN serviceTask element — a fallback if no config entry matches that task's id.
  3. A Camunda process variable named agentProfileKey — last resort.

If none of the three resolve, the run is rejected outright with an error naming the task — a workflow can never silently dispatch with no profile.

Worker​

A Worker is a NodeAgent process — run by you, next to your own infrastructure or CI — that receives RunSpecs and executes the actual CLI (Claude Code, Codex, ...). A new worker uses an enrollment token to self-register and remains PENDING_APPROVAL until an org admin approves it. It then cycles through ONLINE / OFFLINE / DRAINING based on heartbeats. Two transport modes are supported: HTTP (the Backend calls the worker's reachable endpoint) and GRPC (the worker opens an outbound stream, so it does not need a public IP).

Workers advertise provider adapters, tool capabilities, and available slots. Dispatch only selects an online, approved worker that is visible to the organization and satisfies the run's provider and capability requirements. A worker marked public may serve other organizations; a private worker is limited to its owner organization.

What happens if a task fails​

A failed step (e.g. a missing connection binding) surfaces as an incident on that instance. Nothing further happens automatically. Once the underlying problem is fixed (bind the missing connection, correct the profile), click Retry task on the failed run — see Run a Workflow. The workflow instance is preserved, but Camunda schedules the failed task for another attempt and the agent execution may start again from the beginning.