Workflows

A workflow is a pipeline definition owned by a project. Each run of a workflow is a build, executed step by step across workers in a pool.

Anatomy

A workflow groups steps into phases. Phases run in sequence and act as barriers: a phase starts only when every step in the previous phase has finished. Within a phase, steps run in parallel unless they declare a dependency with depends_on.

Definition files

Workflows live in .vulcan/workflows/, one YAML file per workflow, versioned with your code. The file name is the workflow name.

.vulcan/workflows/ci.yaml

pool: default
timeout: 30m

phases:
  - name: verify
    steps:
      - name: unit
        run: cargo test --lib

The full schema — environment, secrets, artifacts, retries — is in Workflow config.

Triggers

• Push — every push to a matched branch. The default from vulcan init.
• Tag — pushes of matching tags, typically for release workflows.
• Schedule — cron expressions, evaluated in UTC.
• Manual — vulcan build trigger, the API, or the Trigger build button in Forge.

Builds

A build is one run of a workflow at a specific commit. Every build, phase, and step carries a single-word status:

• pending — queued, waiting for a worker or a barrier
• running — executing on a worker
• success — exit code 0
• failed — non-zero exit, or timeout
• cancelled — stopped by a user or a newer build
• skipped — upstream dependency failed

Where builds run

Steps execute on workers grouped into pools. A workflow names its pool; if it names none, the organisation’s default pool is used. Pools, worker admission, and capacity are operated by platform admins — see the admin docs.