Skip to main content

Write Kerrigan Workflows

A Kerrigan workflow has two layers:

  • a GitHub Actions job that runs on a Kerrigan runner
  • a checked-in Kerrigan manifest that describes work for the DevKit fleet

GitHub Actions Job​

name: DevKit Smoke

on:
  workflow_dispatch:
  pull_request:

jobs:
  devkit-smoke:
    runs-on: [self-hosted, kerrigan]
    timeout-minutes: 60
    env:
      KERRIGAN_MANIFEST: .kerrigan/smoke.yaml
      KERRIGAN_SERVER_URL: http://fleet-manager:8000
    steps:
      - uses: actions/checkout@v4
      - run: kerrigan-runner-bridge --timeout-sec 3600

Minimal Manifest​

metadata:
  name: devkit-smoke

scheduling:
  max_devkits: 1
  labels:
    kerrigan.board: modalix

tasks:
  - id: uname
    type: command
    command:
      shell: uname -a

Use static manifests committed with the repository. They are easier to review, reproduce, and promote across branches than dynamically generated YAML.

For realistic tests:

  • install runtime packages through source.artifacts or source.vulcan_artifacts
  • select devices with labels instead of hardcoded target IDs
  • set command timeouts and idle-output timeouts
  • add teardown.per_devkit for cleanup that should always run

Install Authoring Skills​

For a local development environment, install the Kerrigan playbooks before authoring workflow manifests:

sima-cli playbooks install gh:sima-neat/kerrigan

This makes Kerrigan-specific workflow authoring guidance available to supported development tools.

The full manifest reference is in the Kerrigan manifest guide and Workflow spec reference.

Watch Progress​

After kerrigan-runner-bridge creates a session, the dashboard shows live progress in Sessions. Use the session list to find the run, then open the detail view to inspect task state counts, assigned DevKits, attempts, exit codes, and collected logs. See Session Dashboard for the full operator flow.