Playbook And Action YAML Reference

This page describes the YAML shapes used for playbooks, actions, and tasks. The schemas live in schema/, and the runtime loaders live in internal/action/.

playbook.yml

Playbooks are the top-level execution documents.

Fields

Import Behavior

Imports are loaded depth-first.

• Imported vars are merged first.
• The importing playbook’s vars override imported vars.
• Imported tasks are prepended in listed order.
• Import cycles are rejected.
• Relative import paths are resolved from the playbook that declares them.

Example

name: lobby-baseline

import:
  - ./base.yml

vars:
  content_root: "C:\\Exhibits\\Lobby"

tasks:
  - name: Prepare content directory
    directory:
      path: "{{ vars.content_root }}"
      ensure: present

action.yml

Actions package reusable tasks behind a typed input surface.

Fields

Input Definition Fields

Example

name: preflight/autologin
version: "1.0.0"
description: Configure Windows automatic login

inputs:
  username:
    type: string
    required: true
  password:
    type: string
    required: false

tasks:
  - name: Enable auto-login
    registry:
      path: 'HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Winlogon'
      values:
        AutoAdminLogon: "1"
        DefaultUserName: "{{ vars.username }}"
        DefaultPassword: "{{ vars.password }}"

Task Shape

Every task requires name. A task may use exactly one execution form:

• uses plus with
• module plus params
• one inline module block such as directory, service, or powershell

Mixing these forms in the same task is an error.

Shared Task Fields

Use id when tasks need a stable dependency key that should not change with display-name edits.

Example:

tasks:
  - name: Prepare content volume
    id: prepare-volume
    directory:
      path: "C:\\Content"
      ensure: present

  - name: Sync content
    module: signage_sync
    depends_on: ["prepare-volume"]
    params:
      source: "\\\\nas01\\content"
      destination: "C:\\Content"

Task Defaults

Playbooks and actions may define:

defaults:
  become:
    enabled: true
    user: exhibit
    method: sudo

Task defaults are inherited into child tasks. become precedence is:

playbook defaults -> action defaults -> task become

If a become object is present and omits enabled, Preflight treats it as enabled. Setting enabled: false on a task disables inherited become for that task.

become

become is task execution metadata, not a module parameter. It changes which user the task runs as while leaving params unchanged.

Example:

tasks:
  - name: Configure kiosk shell
    become:
      user: exhibit
      password: secret:exhibit-password
    powershell:
      script: |
        Write-Output $env:USERNAME

Explicit Module Tasks

Use module and params for plugin-backed modules or when you want an explicit module name:

tasks:
  - name: Sync signage
    module: signage_sync
    params:
      source: "\\\\nas01\\signage"
      destination: "C:\\Signage"

Inline Module Tasks

Use one inline module key when you want a built-in task form:

tasks:
  - name: Ensure content directory exists
    directory:
      path: "C:\\Exhibits\\Content"
      ensure: present

For the exact built-in module fields, see Built-in module reference.

Template Context

Task names, when: expressions, and string parameter values may read from:

The template engine supports simple dot-path lookups such as {{ vars.content_root }}. It renders string values recursively through nested maps and lists, which lets actions template shapes such as registry value lists and power-plan setting arrays. It does not implement the full Jinja filter and expression language.

Action Resolution Order

When Preflight resolves a uses: reference, it checks these sources in order:

1. Embedded stdlib
2. Local project actions under actions/
3. User cache under ~/.preflight/actions
4. Git-backed remote refs

Remote Action Refs

Supported remote refs use this shape:

host/org/repo[/path/to/action]@revision

Examples:

github.com/acme/actions/signage@v1.2.3
github.com/acme/actions/collections/autologin@0123456789abcdef

Remote refs are pinned to exact commit SHAs in preflight.lock for reproducible resolution.

Editor Schema Wiring

The JSON schemas in schema/ enable live validation and autocompletion in editors that support the YAML Language Server protocol (e.g. VS Code with the YAML extension).

Inline file comment (works in any editor with yaml-language-server support):

# yaml-language-server: $schema=https://preflight.dev/schema/action.schema.json
name: myorg/my-action
...

VS Code settings.json (applies to all matching files in the workspace):

{
  "yaml.schemas": {
    "https://preflight.dev/schema/action.schema.json": "**/actions/**/action.yml",
    "https://preflight.dev/schema/playbook.schema.json": "**/playbooks/*.yml",
    "https://preflight.dev/schema/config.schema.json": "**/preflight.yml"
  }
}

Related Docs

• Project config reference
• Inventory reference
• Execution model — action resolution order and lockfile behavior