Workflow Spec Reference

This page is the complete manifest reference for the Kerrigan workflow schema currently accepted by kerrigan-runner-bridge and Fleet Manager.

Top-Level Shape

metadata: {}
source: {}
setup: {}
teardown: {}
scheduling: {}
tasks: []

Only tasks is required. It must be a non-empty list.

`metadata`

metadata:
  name: core-ctest-smoke
  labels:
    suite: core
    priority: nightly

Field	Type	Required	Description
`name`	string	no	Human-readable session name. Defaults to `kerrigan-job`.
`labels`	map	no	Metadata labels for reporting. These do not select devices.

`source`

source:
  repository: sima-neat/core
  ref: refs/heads/develop
  github:
    run_url: https://github.com/sima-neat/core/actions/runs/123
  bundle:
    include:
      - tests/**/*.py
    exclude:
      - tests/experimental/**
  artifacts:
    - name: ctest-runtime
      url: https://example.com/ctest-runtime.tar.gz
      sha256: "<sha256>"
      extract: true
      destination: .
  vulcan_artifacts:
    - env: stg
      name: core
      branch: develop
      tag: latest
      type: minimal
      install_dir: /tmp/kerrigan-core
      base_url: https://artifacts.example.com
      force: false
      skip_devkit_sync: true
      timeout_sec: 900

Field	Type	Required	Description
`repository`	string	no	Source repository. Runner bridge fills this from GitHub Actions when available.
`ref`	string	no	Source ref or SHA. Runner bridge fills this from GitHub Actions when available.
`github`	map	no	GitHub Actions metadata such as `run_url`, `run_id`, `run_attempt`, `workflow`, and `sha`. Runner bridge fills these automatically in Actions.
`bundle.include`	list of strings	no	Glob patterns, relative to the repository root, for small files to inline into the session.
`bundle.exclude`	list of strings	no	Glob patterns to exclude from bundled files.
`artifacts`	list	no	URL/file artifacts downloaded by the device agent before command execution.
`vulcan_artifacts`	list	no	Neat CICD Infrastructure (Vulcan) packages installed by the device agent before command execution.

`source.artifacts[]`

Field	Type	Required	Default	Description
`name`	string	no	`artifact`	Local artifact name.
`url`	string	yes		HTTP(S) or `file://` URL.
`sha256`	string	no		Expected SHA-256 checksum.
`extract`	boolean	no	`true`	Extract as a tarball when true.
`destination`	string	no	`.`	Workspace-relative destination. Absolute paths and `..` are rejected.

`source.vulcan_artifacts[]`

Field	Type	Required	Default	Description
`env`	string	yes		Neat CICD Infrastructure environment, such as `stg`.
`name`	string	yes		Neat CICD Infrastructure package name.
`branch`	string	yes		Package branch.
`tag`	string	yes		Package tag, often `latest` or a git SHA.
`type`	string	no		Passed to `sima-cli neat install --type`.
`install_dir`	string	no		Passed to `--install-dir`.
`base_url`	string	no		Passed to `--base-url`.
`force`	boolean	no	`false`	Adds `--force`.
`skip_devkit_sync`	boolean	no	`false`	Sets `NEAT_INSTALLER_SKIP_DEVKIT_SYNC=ON`.
`timeout_sec`	integer	no	`900`	Install timeout.

Required Neat CICD Infrastructure package fields must be present and non-empty. force and skip_devkit_sync accept booleans or strings such as true, false, 1, and 0.

`setup`

setup:
  per_devkit:
    - id: prepare-runtime
      commands:
        - export PATH="/opt/runtime/bin:$PATH"
        - ./scripts/check-ready.sh
      timeout_sec: 300
      output_idle_timeout_sec: 60
      failure_policy: fail_session

setup.per_devkit runs once on each selected DevKit before normal tasks run.

Each item supports the same command forms as task command:

argv
shell
commands

Field	Type	Required	Default	Description
`id`	string	yes		Setup step ID.
`argv` / `shell` / `commands`	command	yes		Command to run.
`env`	map	no	`{}`	Environment overrides.
`cwd`	string	no	task workspace	Command working directory.
`timeout_sec`	integer	no	`300`	Command timeout.
`output_idle_timeout_sec`	integer	no		Fail if no output appears for this many seconds. Must be `>= 0`.
`failure_policy`	string	no	`fail_session`	Currently documented policy is `fail_session`.

`teardown`

teardown:
  per_devkit:
    - id: cleanup-runtime
      shell: rm -rf /tmp/kerrigan-*
      timeout_sec: 120

teardown.per_devkit has the same item shape as setup.per_devkit. It runs after normal tasks reach terminal state and targets the DevKits used by the session.

`scheduling`

scheduling:
  strategy: spread
  min_devkits: 0
  max_devkits: 4
  max_parallel: 4
  fail_fast: false
  pools:
    - sdk-2-2-som
  capabilities:
    board: modalix
    os_type: elxr
  labels:
    sdk: "2.2.0"
    kerrigan.board: modalix
  tags:
    - 2.2.0-som-devkits

Field	Type	Required	Default	Description
`strategy`	enum	no	`spread`	One of `spread`, `pack`, or `serial`.
`min_devkits`	integer	no	`0`	Minimum eligible DevKits before dispatch starts.
`max_devkits`	integer	no		Maximum distinct DevKits the session may use. Must be `>= 1` when set.
`max_parallel`	integer	no	`max_devkits` or `1`	Maximum concurrent task assignments. Coerced to at least `1`.
`fail_fast`	boolean	no	`false`	Cancel queued work after a test failure.
`pools`	list of strings	no	`[]`	Eligible pool IDs.
`capabilities`	map	no	`{}`	Legacy exact-match device capabilities.
`labels`	map	no	`{}`	Exact-match resource labels.
`tags`	list of strings	no	`[]`	Shorthand tags; each tag also becomes `tag.<name>: true`.

strategy values:

spread: balance assignments across eligible DevKits.
pack: reuse already-selected DevKits before expanding.
serial: run at most one task at a time.

`tasks[]`

Every task requires id. The default task type is command.

Common fields:

Field	Type	Required	Default	Description
`id`	string	yes		Unique task ID.
`type`	string	no	`command`	`command`, `ctest`, or `pytest`.
`requirements`	map	no	`{}`	Task-specific device requirements.
`timeout_sec`	integer	no	`900`	Task command timeout.
`output_idle_timeout_sec`	integer	no		Fail if no output appears for this many seconds. Must be `>= 0`.
`retries.test_failure`	integer	no	`0`	Retries for task result `failed`.
`retries.infra_failure`	integer	no	`0`	Retries for task result `infra_failed`.
`artifacts.junit`	string	no		JUnit artifact pattern reserved for collection/reporting.
`artifacts.include`	list of strings	no	`[]`	Extra artifact include patterns reserved for collection/reporting.
`dependencies`	list of strings	no	`[]`	Task IDs that must pass first.
`estimated_runtime_sec`	integer	no		Scheduling hint and UI metadata.

Task IDs must be unique. Dependencies must refer to known task IDs. Cycles are rejected.

Command Tasks

tasks:
  - id: smoke-shell
    type: command
    command:
      shell: ./scripts/smoke.sh
      env:
        MODE: smoke
      cwd: runtime

Command payload forms:

command:
  argv: ["python3", "-m", "pytest", "-q"]

command:
  shell: ./run-tests.sh --quick

command:
  commands:
    - ./configure.sh
    - ./run-tests.sh

commands are joined with && and executed through sh -c.

CTest Tasks

tasks:
  - id: ctest-core
    type: ctest
    test_dir: ctest-runtime/build/tests
    selector: core_graph_smoke
    args: ["--timeout", "120"]
    env:
      CTEST_OUTPUT_ON_FAILURE: "1"
    cwd: .

Field	Type	Required	Default	Description
`test_dir`	string	no	`build/tests`	Directory passed to `ctest --test-dir`.
`selector`	string	no		Test regex passed to `ctest -R`.
`selectors`	list of strings	no		Expands one manifest task into one task per selector.
`args`	list of strings	no	`[]`	Extra args appended to `ctest`.
`env`	map	no	`{}`	Environment overrides.
`cwd`	string	no	task workspace	Command working directory.

When selectors is used, Kerrigan creates generated task IDs by appending a slugified selector to the original task ID, and each selector is wrapped as an exact CTest regex: ^selector$.

Pytest Tasks

tasks:
  - id: pytest-runtime
    type: pytest
    selector: tests/test_runtime.py::test_smoke

Field	Type	Required	Description
`selector`	string	yes	Pytest file, class, function, or node ID.

Pytest tasks run as:

pytest -q -s <selector>

`requirements`

requirements:
  pools:
    - default
  labels:
    form_factor: som
  tags:
    - uart-debug
  exclusive_target: true
  board: modalix
  os_type: elxr

Field	Type	Default	Description
`pools`	list of strings	`scheduling.pools`	Task-specific pool filter.
`labels`	map	inherited from scheduling	Task-specific exact-match labels.
`tags`	list of strings	inherited from scheduling	Task-specific tags.
`exclusive_target`	boolean	`true`	Whether this task requires an exclusive target lease.
any other key	scalar		Treated as a legacy capability requirement.

Task labels and tags refine session-level labels and tags. For labels, task values override session values for the same key.

Assignment Environment

Device-agent commands run with:

CI=true
SIMA_CLI_CHECK_FOR_UPDATE=0
KERRIGAN_SESSION_ID
KERRIGAN_TASK_ID
KERRIGAN_ATTEMPT
KERRIGAN_TARGET_ID

The agent closes stdin for commands, so workflow commands must not depend on interactive prompts.

Session Status Values

Session status can be:

running
passed
failed
infra_failed
scheduler_failed
cancelled

See Session Dashboard for how these states appear in the operator UI.

Top-Level Shape​

metadata​

source​

source.artifacts[]​

source.vulcan_artifacts[]​

setup​

teardown​

scheduling​

tasks[]​

Command Tasks​

CTest Tasks​

Pytest Tasks​

requirements​

Assignment Environment​

Session Status Values​