Runbooks

A runbook captures an operational task so that anyone with permission can run it safely: restart a service, scale up, run a database migration, flush a cache, rotate a credential. It is the Octopus “runbook” concept, with the same guard rails as deployments.

Defining a runbook

A runbook has parameters, steps (written in pipeline step syntax), a list of environments it may run against, runner labels, a timeout and an approval flag.

name: Scale api
slug: scale-api
service: api
requires_approval: true          # on production
environments: [staging, production]
runs_on: [linux, k8s-prod]
timeout: 15m
parameters:
  - name: replicas
    label: Replica count
    type: number
    required: true
    default: "4"
  - name: reason
    type: string
    required: true
    pattern: "^[A-Za-z0-9 ,.:-]{5,200}$"
steps:
  - name: Scale
    run: kubectl -n api scale deploy/api --replicas "${REPLICAS}"
    env: { REPLICAS: "${{ params.replicas }}" }

Parameter types: string, number, boolean, choice (with options) and secret. A secret parameter holds the name of a stored secret, not the value; it is never echoed back and shows as ********. Names must start with a letter or underscore and contain only letters, digits and underscores.

Running

RunbookService.RunRunbook  (UI: Runbooks, Run)

Pick an environment and fill in parameters. Steps can use ${{ params.x }}, ${{ vars.x }}, ${{ env.* }} and ${{ service.* }}. The run executes as a job on a runner pool that can reach the environment’s infrastructure, so it uses the same network position and identity as deployments.

Guard rails

• RBAC. Running a runbook against an environment requires the environment’s permission, for example environments.deploy:production.
• Approvals. With requires_approval, or when the environment’s protection rules apply to runbooks (apply_to_runbooks: true), the run waits for an approval before starting.
• Audit. Each run records who, where, which parameter values (secrets masked), the logs and the outcome.
• Freezes and windows can be applied to runbooks too, through the environment’s protection rules.

Good uses

Task	Why a runbook
Scale a service for an event	Parameterised, audited, no kubectl access needed
Run a one-off data migration	Approval on production, logs retained
Restart a stuck consumer	Fast, safe, repeatable at 3 a.m.
Rotate a rotated credential	Secret parameter, no value in history