Runbook Structure

Runbook Structure

This page explains the file format and folder organization for a runbook.

File Format

A runbook lives in its own folder and must contain a file named runbook.mdx. This file is written in MDX (Markdown + JSX), which lets you combine:

• Standard Markdown — Headers, paragraphs, lists, code blocks, images, links
• Runbook Blocks — Interactive components like <Check>, <Command>, <Inputs>, and <Template>

You can learn more about:

• Supported markdown elements
• Available blocks

Common structure

While you can organize your runbook.mdx file however you like, here’s a common pattern:

# Runbook Title

Introduction paragraph explaining what this runbook does.

## Pre-flight Checks

Make sure the user is set up for success.

<Check
    id="pre-flight-checks"
    command="tool --version"
    title="Check if required tool is installed"
    successMessage="Tool is installed!"
    failMessage="Please install the tool first"
/>

## Execute Actions

Run commands on behalf of the user to complete the runbook.

<Command
    id="do-something"
    command="echo {{ .ProjectName }}"
    inputsId="config"
    title="Execute action"
    successMessage="Done!"
/>

## Generate Code

Generate code the user needs to accomplish their task.

<Template
    id="infra-code"
    path="templates/infra"
/>

## Post-flight Checks

Verify everything worked.

<Check
    id="post-flight-checks"
    command="curl https://some-endpoint.com"
    title="Check if deployment is successful"
    successMessage="Deployment successful"
    failMessage="Something went wrong"
/>

Folder organization

Blocks often reference scripts and templates stored in folders. While you can store these anywhere, here’s the conventional folder structure:

• Directorymy-runbook/

  • runbook.mdx Main runbook file
  • Directoryassets/ Images and other assets

    • diagram.png
  • Directorychecks/ Shell scripts for <Check> blocks

    • prereq1.sh
    • prereq2.sh
  • Directoryscripts/ Shell scripts for <Command> blocks

    • deploy.sh
    • cleanup.sh
  • Directorytemplates/ Boilerplate templates for <Template> blocks

    • Directorymy-template/

      • boilerplate.yml
      • main.tf
      • variables.tf

Folder Purposes

| Folder | Purpose | Used By | |--------|---------|---------| | assets/ | Images, diagrams, and other static files | Markdown image syntax | | checks/ | Shell scripts that validate prerequisites | <Check> blocks | | scripts/ | Shell scripts that execute actions | <Command> blocks | | templates/ | Boilerplate template directories | <Template> blocks |

Relative Paths

Always reference files relative to your runbook:

<Check path="checks/prereq.sh" ... />
<Template path="templates/my-template" ... />
![Diagram](./assets/diagram.png)