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.

You can edit in either direction: changes to the form update the YAML, and direct YAML edits update the form.

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 from top to bottom. Use the reorder controls to change the order.

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. To restrict access:

1. Open the Client Access section in the editor.
2. Toggle off global access.
3. Select specific clients that should have access.

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

Versioning

Every time you save a runbook, a new immutable version is created. Previous versions are preserved and can be viewed in the Version History tab.

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. The dropdown lists all 10 available actions grouped by risk tier (read_only, operational, destructive).
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 order from top to bottom. Use the reorder controls (drag handle or up/down arrows) to rearrange them.

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

1. Scroll to the Client Access section at the bottom of the form.
2. By default, new runbooks are global (visible to all clients).
3. To restrict access, toggle off global access.
4. Select specific clients from the multi-select dropdown.
5. Only users who have access to at least one selected client will be able to view or execute the runbook.