Sign In

Creating Runbooks

Create runbooks to document your team’s operational procedures in a clear, executable format.

Getting Started

Access Runbooks

  1. Navigate to your project
  2. Click Runbooks in the sidebar
  3. Click Create Runbook

Basic Setup

Enter the essential information:

Title

  • Use a clear, descriptive name
  • Include the service or system
  • Example: “Restart Payment Service”

Description

  • Brief explanation of what this runbook does
  • When to use it
  • Any warnings or prerequisites

Status

  • Start with Draft while building
  • Change to Published when ready for use

![Placeholder: Create Runbook Form with Title, Description, and Status Fields]

Adding Steps

Create Your First Step

  1. Click Add Step
  2. Give the step a clear title
  3. Write detailed instructions
  4. Click Save Step

![Placeholder: Add Step Dialog with Rich Text Editor]

Writing Good Instructions

Keep each step focused:

Step 1: Check Current Service Status

Instructions:
1. SSH to the production server
2. Run: systemctl status payment-service
3. Note if the service is active or failed
4. Check the last log entries shown

Using Rich Text

The editor supports:

  • Bold for emphasis
  • Code formatting for commands
  • Numbered and bullet lists
  • Links to documentation

Decision Steps

Simple Branching

Create decision points that route to different steps:

Step 5: Is the service running?

Check the status from Step 1.

If YES: Continue to Step 6
If NO: Skip to Step 10 (Restart Procedure)

Setting Up Navigation

  1. Create all your steps first
  2. Note the step numbers
  3. Add “Go to step X” instructions
  4. Test the flow makes sense

Step Management

Reordering Steps

  • Drag steps to reorder them
  • Numbers update automatically
  • Remember to update any “Go to” references

![Placeholder: Runbook Editor Showing Draggable Steps with Reorder Handles]

Editing Steps

  • Click the edit icon on any step
  • Make your changes
  • Save the step

Deleting Steps

  • Click the delete icon
  • Confirm deletion
  • Update any references to that step

Testing Your Runbook

While in Draft

  1. Use Execute to test the flow
  2. Follow each step yourself
  3. Check decision routing works
  4. Make edits as needed

Getting Feedback

  • Have a teammate test it
  • Note any confusing parts
  • Update instructions for clarity
  • Add missing information

Publishing

Ready to Publish

When your runbook is tested and complete:

  1. Click Edit Runbook
  2. Change status to Published
  3. Save changes

After Publishing

  • Runbook appears in the main list
  • Team members can execute it
  • You can still edit if needed
  • Consider archiving old versions

Best Practices

Keep Steps Simple

  • One main action per step
  • Clear success criteria
  • Include exact commands
  • Note expected output

Be Specific

  • Don’t say “check the logs”
  • Say “check /var/log/app.log for errors”
  • Include file paths
  • Specify exact values

Plan for Problems

  • What if a step fails?
  • Include troubleshooting tips
  • Know when to escalate
  • Have rollback steps

Maintain Your Runbooks

  • Review after incidents
  • Update changed procedures
  • Archive outdated ones
  • Get team feedback

Common Examples

Service Restart

  1. Check current status
  2. Notify team of restart
  3. Stop service gracefully
  4. Wait for connections to close
  5. Start service
  6. Verify it’s running
  7. Check key functionality

Deployment Rollback

  1. Identify the issue
  2. Find last working version
  3. Take service offline
  4. Deploy previous version
  5. Restart service
  6. Verify functionality
  7. Notify stakeholders

Database Maintenance

  1. Check current metrics
  2. Set maintenance mode
  3. Run maintenance tasks
  4. Verify completion
  5. Exit maintenance mode
  6. Check performance

Learn more