Write An Action

on this page

When To Reach For An Action 1. Create The Action Directory 2. Define action.yml 3. Call The Action From A Playbook 4. Inspect The Action 5. Validate The Calling Playbook Notes

Use this guide when you want to package a reusable task sequence behind named inputs.

When To Reach For An Action

Write an action when you have a task sequence that should be:

reused across several playbooks
parameterized with inputs
shared inside a project or fetched remotely later

If the logic is only needed once, keep it inline in the playbook instead.

1. Create The Action Directory

Project-local actions live under actions/:

text

actions/
  myorg/
    display-config/
      action.yml

The resulting ref is:

text

myorg/display-config

2. Define `action.yml`

Example:

yaml

name: myorg/display-config
version: "1.0.0"
description: Prepare a content directory and drop a marker file

inputs:
  content_root:
    type: path
    required: true
    description: Target content directory
  label:
    type: string
    default: default
    description: Marker text

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

  - name: Write content marker
    shell:
      cmd: /bin/sh
      args:
        - -c
        - printf '%s\n' "{{ vars.label }}" > "{{ vars.content_root }}/marker.txt"
      creates: "{{ vars.content_root }}/marker.txt"

Important details:

name should match the ref you plan to use.
inputs define the external API of the action.
Inside the action, inputs become template variables under vars.*.
Tasks inside an action use the same task schema as playbooks.

3. Call The Action From A Playbook

yaml

tasks:
  - name: Prepare lobby content
    uses: myorg/display-config
    with:
      content_root: "./tmp/lobby"
      label: lobby

During planning, Preflight resolves the action, renders the with: values, applies any input defaults, verifies required inputs, and expands the action’s tasks into the final execution plan.

4. Inspect The Action

Use the built-in inspection commands:

bash

preflight action list
preflight action info myorg/display-config

action info is the fastest way to confirm the action name, inputs, and task count are what you expect.

5. Validate The Calling Playbook

bash

preflight validate playbooks/lobby.yml
preflight plan playbooks/lobby.yml

That verifies both the playbook and the action ref, then shows the expanded tasks after action resolution.

Notes

Resolution order is embedded stdlib, then local actions/, then the user cache, then Git-backed refs.
The embedded stdlib in this repo includes leaf actions such as preflight/autologin, plus grouped Windows actions such as preflight/windows-machine and preflight/windows-power.
Remote actions can be fetched and pinned into preflight.lock, but you do not need that machinery for project-local actions.