Sign In

Creating Runbooks

Create runbooks to document your team’s operational procedures.

Prerequisites

  • Access to a project in Upstat

Creating a New Runbook

1. Navigate to Runbooks

Go to Runbooks in your project sidebar.

2. Click Create

Click Create Runbook to open the runbook wizard.

3. Enter Basic Information

Title Use a clear, descriptive name that includes the service or system. Example: “Restart Payment Service”

Description Briefly explain what this runbook does and when to use it.

4. Set Status

Start with Draft while building your runbook. Change to Published when ready for use.

Adding Steps

1. Click Add Step

Click the add step button to create a new step.

2. Write the Step Title

Give each step a clear title that summarizes the action.

3. Write Instructions

In the step content area, provide detailed instructions. The editor supports:

  • Bold and italic text
  • Code blocks for commands
  • Numbered and bullet lists
  • Links to external documentation

4. Save the Step

Click Save to add the step to your runbook.

Writing Good Steps

Keep steps focused Each step should cover one main action. Split complex actions into multiple steps.

Be specific Include exact commands, file paths, and expected output.

Include verification Tell users how to confirm the step succeeded.

Example step:

Step 3: Restart the Service

Run the following command:
sudo systemctl restart payment-service

Verify the service is running:
systemctl status payment-service

You should see "active (running)" in the output.

Reordering Steps

Drag steps to reorder them. Step numbers update automatically.

If you have decision steps that reference specific step numbers, update those references after reordering.

Editing and Deleting Steps

Edit: Click on any step to modify its content.

Delete: Click the delete icon on a step to remove it. Confirm the deletion when prompted.

Publishing Your Runbook

1. Test the Flow

Use the Execute option to test your runbook while in draft mode. Walk through each step to verify the flow makes sense.

2. Get Feedback

Have a teammate review the runbook before publishing.

3. Publish

Change the status to Published to make the runbook available to your team.

Best Practices

Start with common tasks Document procedures your team performs weekly or during incidents.

Keep steps simple “Check status” instead of “Check status and restart if needed” (split into separate steps).

Include exact values Specify file paths, command arguments, and expected output.

Maintain your runbooks Update procedures when your infrastructure changes.

Result

Your runbook appears in the runbooks list and can be executed by team members.