Skip to content
Vulcan CIVulcan CI

Workflow config

Workflows are YAML files in .vulcan/workflows/. The file name is the workflow name: ci.yaml defines the ci workflow.

Full example

Section titled “Full example”
.vulcan/workflows/ci.yaml
pool: default
timeout: 30m
concurrency: 1          # newer builds cancel older ones


on:
  push:
    branches: [main, release/*]
  schedule: "0 6 * * 1"  # mondays 06:00 UTC


phases:
  - name: verify
    steps:
      - name: lint
        run: cargo clippy -- -D warnings
      - name: unit
        run: cargo test --lib
        retry: 1
      - name: integration
        run: cargo test --test '*'
        depends_on: [unit]
        env:
          RUST_LOG: info
  - name: package
    steps:
      - name: image
        run: docker build -t payments-api .
        artifacts: [target/sbom.json]

Top-level keys

Section titled “Top-level keys”
Key Type Description
pool string Worker pool to run on. Defaults to the organisation’s default pool.
timeout duration Whole-build limit, e.g. 30m, 2h. Default 1h. On expiry the build is failed.
concurrency integer Maximum simultaneous builds of this workflow per ref. 1 cancels superseded builds.

on

Section titled “on”
Key Type Description
push mapping branches, a list of glob patterns. Omit the key entirely to disable push triggers.
tag mapping patterns, glob-matched against tag names, e.g. [v*].
schedule string Five-field cron expression, evaluated in UTC, run against the default branch.

Manual triggers (vulcan build trigger, the API, Forge) are always available and need no configuration.

phases

Section titled “phases”

Phases run in file order and act as barriers. Each entry has a name and a steps list. A phase with no steps is a validation error.

steps

Section titled “steps”
Key Type Description
name string Unique within the workflow. Shown in Forge and in vulcan build watch.
run string Shell command, executed with sh -c in the repository root.
depends_on list Step names within the same phase. The step waits for them and is skipped if any fail.
env mapping Environment variables for this step. Merged over project-level variables.
retry integer Automatic re-runs on failure. Default 0, maximum 3.
artifacts list Glob patterns of files to retain after the step, downloadable from the build page.

Environment and secrets

Section titled “Environment and secrets”

Plain variables belong in env. Secrets are defined per project in Forge under Settings → Secrets and injected as environment variables prefixed VULCAN_SECRET_:

- name: publish
  run: cargo publish --token $VULCAN_SECRET_CRATES_TOKEN