Sign In

Runbook Decision Steps

Decision steps let you create different paths through a runbook based on what happens during execution.

What Are Decision Steps?

Decision steps are regular steps that include instructions to jump to different steps based on conditions. They help handle different scenarios within the same runbook.

Creating Decision Steps

Basic Format

Write your decision step like any other step, but include clear routing instructions:

Step 5: Check Service Status

Run: systemctl status myapp

Based on the output:
- If service is "active (running)" - Continue to Step 6
- If service is "failed" - Go to Step 10 (Restart Procedure)
- If service is "inactive" - Go to Step 15 (Start Procedure)

Simple Yes/No Decisions

The most common type of decision:

Step 8: Did the restart succeed?

Check if the service is now running properly.

YES - Continue to Step 9 (Verify Functionality)
NO - Go to Step 20 (Escalation Procedure)

How Users Navigate

During execution, users:

  1. Read the decision question
  2. Evaluate the condition
  3. Click on the target step number
  4. Continue from the new location

Clear Routing

Make navigation obvious:

  • Use “Go to Step X” format
  • Include step titles for clarity
  • Bold or highlight the routing

Good example:

If error persists:
**Go to Step 12** (Advanced Troubleshooting)

Otherwise:
**Continue to Step 7**

Best Practices

Keep It Simple

  • Limit to 2-4 options per decision
  • Use clear, distinct conditions
  • Avoid complex logic trees

Be Specific

  • Define exact conditions
  • Include examples if helpful
  • Remove ambiguity

Instead of: “If it looks wrong” Use: “If status shows ‘Connection refused’”

Plan Your Flow

  1. Map out paths before creating steps
  2. Number steps to leave room for branches
  3. Test each path during draft phase

Common Patterns

Service Health Check

Step 3: Is the service healthy?

Check endpoint: curl http://localhost:8080/health

- Returns 200 OK → Continue to Step 4
- Returns 500 error → Go to Step 10 (Investigate Errors)
- No response → Go to Step 15 (Service Down Procedure)

Error Handling

Step 7: Did the command succeed?

Check for error messages in the output above.

- No errors → Continue to Step 8
- "Permission denied" → Go to Step 20 (Access Issues)
- Other errors → Go to Step 25 (General Troubleshooting)

Validation Gate

Step 12: Pre-deployment Check

Verify all conditions are met:
- Build passed? ✓
- Tests green? ✓
- Approval received? ✓

All YES → Continue to Step 13 (Deploy)
Any NO → Go to Step 30 (Abort Deployment)

Tips for Success

Number Your Steps Wisely

  • Leave gaps between sections (1-5, 10-15, 20-25)
  • Makes it easier to add steps later
  • Groups related procedures

Document the Decision

  • Explain what to check
  • Give specific values or thresholds
  • Include commands to run

Test Your Branches

  • Execute the runbook multiple times
  • Try each path
  • Verify steps link correctly

Limitations

Current Limitations

  • No automatic condition evaluation
  • Users manually navigate to steps
  • No complex logic expressions
  • Basic “go to” navigation only

Working Within Limits

  • Keep decision logic simple
  • Provide clear instructions
  • Test thoroughly
  • Consider separate runbooks for very different paths

Examples in Practice

Restart with Fallback

1. Stop service
2. Wait 30 seconds
3. Start service
4. Check if service started?
   - YES: Go to Step 5
   - NO: Go to Step 10 (Force Restart)
5. Verify functionality
6. Complete

10. Force restart procedure
11. Kill any remaining processes
12. Clear temp files
13. Start service with debug logging
14. Go to Step 5

Deployment Decision Tree

1. Check current version
2. Confirm target version
3. Is this a hotfix?
   - YES: Go to Step 10 (Hotfix Deploy)
   - NO: Continue to Step 4
4. Run full test suite
5. All tests passing?
   - YES: Go to Step 20 (Standard Deploy)
   - NO: Stop - fix tests first

10. Hotfix deployment...
20. Standard deployment...

Learn more