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. Format: owner/repo/path@ref.

steps[].shell

• Type: string
• Required: No
• Default: sh
• Allowed values: sh, bash, zsh
• Description: Shell to use for executing run commands.

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
• Required: No
• Default: false
• Description: If true, the workflow pauses after this step completes and waits for human approval in the desktop app before continuing.

Annotated Example

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

on:
  push:
    branches: ['**'] # Match all branches

jobs:
  default: # Job key
    name: Lint, Test & Deploy # Job display name
    steps:
      - name: lint # Step name (unique within job)
        uses: airlock-hq/airlock/defaults/lint@main # Reusable step

      - name: freeze
        run: airlock exec freeze # Shell command

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

      - name: test
        uses: airlock-hq/airlock/defaults/test@main

      - name: review
        run: 'true'
        require-approval: true # Pause for human approval

      - 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