Creating & Editing Runbooks

Prerequisites

You need the runbooks:write permission to create or edit runbooks.

Navigating to the Editor

1. Open Automation > Runbooks in the sidebar.
2. Click New Runbook to create, or click an existing runbook and select Edit.

Editor Layout

The editor uses a two-column layout:

• Left column -- Form builder with fields for metadata, parameters, and steps.
• Right column -- Live YAML preview that updates as you edit the form.

The flow is one-way: the form drives the YAML. The preview is read-only — there is no YAML parser in the editor, and the API takes a JSON definition. Copy the YAML out for version control or review; you cannot paste it back in.

Metadata

Field	Required	Description
Name	Yes	Human-readable name (e.g., "Restart Nginx")
Slug	Yes	URL-safe identifier (e.g., restart-nginx). Must be unique.
Description	No	What this runbook does and when to use it.
Risk Tier	Yes	read_only, operational, or destructive. Must be >= the highest risk action in the steps.
Timeout (seconds)	No	Maximum execution time. Default: 300 (5 minutes).

Parameters

Parameters let callers customize runbook behavior at execution time.

Click Add Parameter to define each one:

Field	Description
Name	Parameter identifier used in step references (e.g., threshold).
Type	string, int, bool, or enum.
Required	Whether the caller must provide this value.
Default	Value used if the caller does not provide one.
Description	Help text shown to operators.

Type-specific constraints:

• int -- min and max bounds.
• string -- pattern (regex) for validation.
• enum -- List of allowed values.

Example

params:
  service:
    type: string
    required: true
    description: "Systemd unit name"
  log_lines:
    type: int
    default: 50
    min: 10
    max: 500

Steps

Steps are the ordered actions that execute on the target host.

Click Add Step to define each one:

Field	Description
ID	Unique identifier within this runbook (e.g., check_logs). Used for cross-step references.
Name	Human-readable step name.
Action	Select from the 10 available actions (see Action Reference).
Params	Key-value pairs passed to the action. Supports {{ param }} and {{ step_id.field }} substitution.
When	Conditional expression. Step is skipped if the condition evaluates to false.
On Failure	What to do if this step fails: abort (default), warn, or skip.

Step Ordering

Steps execute sequentially in the order they were added. There are no reorder controls — the grip icon on each step card is decorative (no drag handlers, no drag-and-drop library), and the only button on a step header is delete. To change the order, delete and re-add the steps.

Conditional Steps

The when field accepts expressions that reference previous step outputs:

steps:
  - id: check
    action: read_file_tail
    params:
      path: "/var/log/syslog"
      lines: 20
  - id: restart
    action: restart_systemd_unit
    when: "{{ check.lines_read > 0 }}"
    params:
      unit: "{{ service }}"

Failure Policies

Policy	Behavior
abort	Stop execution immediately. Execution status becomes failed. This is the default.
warn	Log the failure and continue to the next step.
skip	Mark the step as skipped and continue.

Client Access

By default, a new runbook is global -- visible to all clients.

There is no Client Access UI

The editor has three sections — Metadata, Parameters, Steps — and no client-access control. Restricting a runbook is API-only:

GET  /api/v1/runbooks/{id}/access
PUT  /api/v1/runbooks/{id}/access

A runbook stays global unless its access list is set through that endpoint.

Only users with access to an allowed client can view or execute a restricted runbook.

Versioning

Every time you save a runbook, a new immutable version is snapshotted server-side.

No version-history UI

The editor has two tabs, Editor and Executions — there is no Version History tab. Snapshots are readable via GET /api/v1/runbooks/{id}/versions only.

When a runbook executes, it records which version was used. This means you can update a runbook without affecting in-flight executions.

Saving

Click Save to validate and persist the runbook. The backend validates:

• All required metadata fields are present.
• At least one step is defined.
• All step actions exist in the action registry.
• Step IDs are unique.
• when conditions reference only preceding steps.
• The runbook's risk tier covers its most dangerous action.
• Parameter types and constraints are valid.

If validation fails, the editor displays the error and the runbook is not saved.

Using the Editor

This section walks through the editor workflow from start to finish.

Two-Column Layout

The editor splits the screen into two columns:

• Left column (Form Builder) -- Interactive form with collapsible sections for metadata, parameters, steps, and client access. All fields have labels, placeholders, and inline validation.
• Right column (YAML Preview) -- Read-only YAML output that updates live as you make changes in the form. Use this to verify the final structure before saving.

The YAML preview reflects every form change immediately -- there is no separate "generate" step.

Filling in Metadata

1. Enter a Name (e.g., "Restart Nginx"). The Slug field auto-generates a URL-safe identifier from the name (e.g., restart-nginx). You can override the slug manually if needed.
2. Add an optional Description explaining what the runbook does and when to use it.
3. Select a Risk Tier from the dropdown: read_only, operational, or destructive. This must be greater than or equal to the highest-risk action used in any step.
4. Optionally adjust the Timeout (in seconds). The default is 300 (5 minutes).

Adding Parameters

1. Click Add Parameter to create a new parameter row.
2. Enter the parameter Name (used as the identifier in step references).
3. Select the Type from the dropdown: string, int, bool, or enum.
4. Set whether the parameter is Required.
5. Enter a Default value if desired.
6. Add a Description (shown to operators when executing).
7. For type-specific constraints:
   • int -- Set min and max bounds.
   • string -- Set a pattern (regex) for validation.
   • enum -- Add allowed values to the list.

Repeat for each parameter. The YAML preview updates with each addition.

Adding Steps

1. Click Add Step to create a new step.
2. Enter a unique ID (e.g., check_service) and a human-readable Name.
3. Select an Action from the dropdown. It is a flat list of the ten registry actions with the risk tier shown in parentheses — not grouped, and not in a stable order (it follows Go map iteration).
4. Fill in the action-specific Params as key-value pairs. Use {{ param_name }} to reference parameters and {{ step_id.field }} to reference previous step outputs.
5. Optionally set a When condition to make the step conditional.
6. Choose an On Failure policy: abort (default), warn, or skip.

Steps execute in the order they were added. The grip icon is decorative — there is no drag-and-drop and no up/down arrows.

Live YAML Preview

As you fill in each section, the right-column YAML preview updates in real time. This lets you:

• Verify the structure matches your intent before saving.
• Catch mistakes early (e.g., a missing parameter reference, a mistyped action name).
• Copy the YAML for use in version control or sharing with teammates.

Configuring Client Access

There is no form section for this — see the Client Access caution above. Set the access list with PUT /api/v1/runbooks/{id}/access; until you do, the runbook is global.