Find runbooks in a project
find_runbooksList or fetch runbooks in an Octopus Deploy project by ID, slug, or git ref, with filtering options for partial name and pagination.
Instructions
Find runbooks in an Octopus Deploy project.
Two project kinds are supported:
DB-backed projects: address runbooks by 'runbookId' (e.g. 'Runbooks-123'). The summary includes 'publishedRunbookSnapshotId', which run_runbook uses by default.
Config-as-Code (CaC) projects: pass 'gitRef' (branch name like 'main', tag, or commit SHA). Address a single runbook by 'runbookSlug'. The summary includes 'gitRef' instead of 'publishedRunbookSnapshotId'; run_runbook needs the same gitRef.
Modes:
runbookId → fetch a single DB runbook.
runbookSlug + gitRef → fetch a single CaC runbook.
gitRef alone → list CaC runbooks at that ref.
neither → list DB runbooks in the project (optionally filtered by partialName).
Each summary includes multiTenancyMode and environmentScope so callers can determine which environments and tenants are valid targets before invoking run_runbook.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| spaceName | Yes | Space name. | |
| projectName | Yes | Project name. Runbooks are scoped to a project, so this is required for both single fetch and listing. | |
| runbookId | No | Fetch a single DB-backed runbook by ID (e.g. 'Runbooks-123'). Mutually exclusive with partialName/skip/take and with gitRef/runbookSlug. | |
| runbookSlug | No | Config-as-Code only. Fetch a single CaC runbook by slug at the given gitRef. Requires gitRef. | |
| gitRef | No | For Config-as-Code projects only. A branch name (e.g. 'main'), tag, or commit SHA. Use get_branches to list available branches. | |
| partialName | No | Filter listing by partial runbook name (case-insensitive). | |
| skip | No | Pagination offset. | |
| take | No | Pagination page size. |