Workflow YAML Schema

Workflow files live in .airlock/workflows/*.yml. This page documents every field and its constraints.

Top-Level Structure

name: <string> # Required. Human-readable workflow name.

on: # Required. Trigger configuration.
  push:
    branches: <string[]> # Required. Glob patterns for branch matching.

jobs: # Required. Map of job definitions.
  <job-key>:
    name: <string>
    needs: <string[]>
    steps: <step[]>

name

• Type: string
• Required: Yes
• Description: Human-readable name displayed in the desktop app and CLI output.

on

Defines when the workflow triggers.

on.push

• Type: object
• Description: Trigger on push events.

on.push.branches

• Type: string[]
• Required: Yes
• Description: Glob patterns for matching branch names. Use ['**'] to match all branches.

jobs

A map of job keys to job definitions. Each key is a unique identifier for the job.

jobs.<key>.name

• Type: string
• Required: No
• Description: Human-readable job name. Defaults to the job key.

jobs.<key>.needs

• Type: string[]
• Required: No
• Description: List of job keys that must complete before this job starts. Use this to create parallel execution with dependencies.

jobs.<key>.steps

• Type: step[]
• Required: Yes
• Description: Ordered list of steps to execute.

Steps

Each step is an object with the following fields:

steps[].name

• Type: string
• Required: Yes
• Description: Unique identifier for the step within its job.

steps[].run

• Type: string
• Required: No (mutually exclusive with uses)
• Description: Shell command to execute. Can be a multi-line string using YAML | syntax.

steps[].uses

• Type: string
• Required: No (mutually exclusive with run)
• Description: Reference to a reusable step definition. Supports two formats:
  • Git repository: owner/repo/path@ref — fetches the step from a remote repo
  • Local directory: ./path — resolves from the repository root (e.g., ./my-steps/lint). Path traversal outside the repo is blocked. Looks for step.yml, action.yml, or stage.yaml in the referenced directory.

steps[].shell

• Type: string
• Required: No
• Default: User's login shell ($SHELL -l)
• Allowed values: sh, bash, zsh
• Description: Shell to use for executing run commands. When omitted, the user's login shell is used with -l (login mode), giving steps full access to the user's environment (API keys, PATH, version managers, etc.).

steps[].env

• Type: Record<string, string>
• Required: No
• Description: Environment variables to set for this step. These are available to both run scripts and uses step definitions.

- name: review
  uses: airlock-hq/airlock/defaults/gate@main
  env:
    AIRLOCK_RISK_THRESHOLD: medium

steps[].model

• Type: string
• Required: No
• Description: Override the AI model for this step. Sets AIRLOCK_AGENT_MODEL during execution, which takes precedence over the global agent.options.model in config. Useful for running expensive steps with a smaller model or vice versa.

- name: describe
  uses: airlock-hq/airlock/defaults/describe@main
  model: haiku

steps[].adapter

• Type: string
• Required: No
• Description: Override the AI agent adapter for this step. Sets AIRLOCK_AGENT_ADAPTER during execution, which takes precedence over the global agent.adapter in config.

- name: critique
  uses: airlock-hq/airlock/defaults/critique@main
  adapter: claude-code

steps[].continue-on-error

• Type: boolean
• Required: No
• Default: false
• Description: If true, the workflow continues even if this step fails. The step is marked as failed in the Activity tab but does not stop execution.

steps[].require-approval

• Type: boolean | "if_patches"
• Required: No
• Default: false
• Description: Controls whether the workflow pauses after this step completes to wait for human approval in the desktop app.

For conditional approval logic, prefer using airlock exec await inside a run script instead. This gives you full shell scripting control over when to pause — for example, pausing only when tests fail or when critical issues are found.

steps[].apply-patch

• Type: boolean
• Required: No
• Default: false
• Description: When true, the executor auto-applies all pending patches from $AIRLOCK_ARTIFACTS/patches/ after this step passes and commits them. This replaces the need for a separate freeze step in most workflows.

- name: lint
  uses: airlock-hq/airlock/defaults/lint@main
  apply-patch: true # Commit lint fixes after this step passes

Annotated Example

# .airlock/workflows/main.yml
name: Main Pipeline

on:
  push:
    branches: ['**']

jobs:
  rebase:
    name: Rebase
    steps:
      - name: rebase
        uses: airlock-hq/airlock/defaults/rebase@main

  critique: # Runs in parallel with test
    name: Critique
    needs: rebase
    steps:
      - name: critique
        uses: airlock-hq/airlock/defaults/critique@main

  test: # Runs in parallel with critique
    name: Test
    needs: rebase
    steps:
      - name: test
        uses: airlock-hq/airlock/defaults/test@main

  gate: # AI-driven risk assessment
    name: Review Gate
    needs: [critique, test]
    steps:
      - name: review
        uses: airlock-hq/airlock/defaults/gate@main
        env:
          AIRLOCK_RISK_THRESHOLD: medium # never, low, medium, or high

  deploy:
    name: Lint & Push
    needs: [describe, document]
    steps:
      - name: lint
        uses: airlock-hq/airlock/defaults/lint@main
        apply-patch: true # Auto-commit lint fixes
      - name: push
        uses: airlock-hq/airlock/defaults/push@main
      - name: create-pr
        uses: airlock-hq/airlock/defaults/create-pr@main

Related

• Workflows — Conceptual overview
• Custom Workflows — Practical guide to building workflows
• Default Steps — Built-in step definitions