Run a runbook in Octopus Deploy
run_runbookExecute operational runbooks (e.g., DB backups, smoke tests) in Octopus Deploy across one or more environments, with support for tenanted runs, snapshot or git ref selection, and optional scheduling.
Instructions
Run a runbook against one or more environments in Octopus Deploy.
Runbooks execute operational processes (DB backups, smoke tests, environment refresh, etc.) against the specified environments. For tenanted runs, supply tenants and/or tenantTags.
Two project kinds:
DB-backed projects: by default the runbook's published snapshot is used; pass runbookSnapshotId to pick a specific snapshot.
Config-as-Code projects: pass gitRef (branch name like 'main', tag, or commit SHA). Snapshots don't apply — the gitRef is the version pin. Use find_runbooks with the same gitRef to discover runbook names.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| spaceName | Yes | The space name | |
| projectName | Yes | The project name | |
| runbookName | Yes | The runbook name (within the project) | |
| environmentNames | Yes | Array of environment names. At least one environment must be provided. | |
| tenants | No | Array of tenant names for tenanted runs (optional) | |
| tenantTags | No | Array of tenant tags for tenanted runs (e.g., ['Region/US-West', 'Tier/Production']) | |
| runbookSnapshotId | No | DB-backed runbooks only. Specific snapshot ID. Defaults to the runbook's published snapshot if omitted. Not applicable to Config-as-Code runbooks. | |
| gitRef | No | Config-as-Code runbooks only. A branch name (e.g. 'main'), tag, or commit SHA. Use get_branches to list available refs. Mutually exclusive with runbookSnapshotId. | |
| promptedVariableValues | No | Prompted variable values as key-value pairs | |
| useGuidedFailure | No | Use guided failure mode | |
| forcePackageDownload | No | Force package download | |
| specificMachineNames | No | Run on specific machines only | |
| excludedMachineNames | No | Exclude specific machines from the run | |
| skipStepNames | No | Skip specific runbook steps | |
| runAt | No | Schedule run for later (ISO 8601 date string) | |
| noRunAfter | No | Don't run after this time (ISO 8601 date string) | |
| confirm | No | Required only when the MCP client does not support elicitation. Set to true to confirm the run; otherwise the tool aborts. |