Sign in
Runbooks

Create a new Runbook or clone an existing Runbook.

post/projects/{projectId}/runbooks

Path parameters

projectIdstring required

The Project that contains the Runbook.

Request body

Clonestring

The ID of an existing database runbook to copy. Cloning brings across the source runbook's settings, its process and steps, and any project triggers that target it. The source runbook's tags come across too, unless you supply RunbookTags. Leave unset to create a runbook from scratch, which starts with an empty process.

DefaultGuidedFailureMode'EnvironmentDefault' | 'Off' | 'On'

What a run does when a step fails. One of 'EnvironmentDefault' (follow the target environment's setting), 'Off' (fail the run immediately, the default), or 'On' (pause the run and wait for someone to choose whether to retry, ignore or abort).

Descriptionstring

The description of the Runbook to create.

Environmentsstring[]

The environments the runbook may be run in. Only applies when EnvironmentScope is 'Specified'; ignored otherwise.

EnvironmentScope'All' | 'Specified' | 'FromProjectLifecycles'

Which environments the runbook may be run in. One of 'All' (every environment in the space, the default), 'Specified' (only the environments listed in Environments), or 'FromProjectLifecycles' (only the environments used by the project's lifecycles).

ForcePackageDownloadboolean

Re-download every package on each run instead of reusing the copy already cached on the deployment target.

MultiTenancyMode'Untenanted' | 'TenantedOrUntenanted' | 'Tenanted'

Whether the runbook can be run for tenants. One of 'Untenanted' (untenanted runs only, the default), 'Tenanted' (a tenant must be supplied for every run), or 'TenantedOrUntenanted' (either is allowed).

Namestring required

The name of the Runbook to create.

ProjectIdstring required

The ID of the project to create the runbook in. Must be a project that stores its runbooks in the Octopus database.

PublishedRunbookSnapshotIdstring

Leave unset. A snapshot can only be published after the runbook exists and has a process.

RunbookProcessIdstring

Leave unset. Octopus creates an empty runbook process for the new runbook and links it automatically.

RunbookTagsstring[]

Tags to apply to the runbook, each written as "TagSet/Tag" using either the names or the IDs of the tag set and tag (for example "Ops/Nightly"). Call find_tag_sets to discover which tag sets apply to runbooks and what tags they contain.

Slugstring

A short URL-friendly identifier for the runbook, unique within the project. Generated from the name when omitted.

SpaceIdstring required

The ID of the space containing the resource(s).

Example request

{
  "Clone": "Runbooks-1",
  "Environments": [
    "Environments-1",
    "..."
  ],
  "ProjectId": "Projects-1",
  "RunbookProcessId": "RunbookProcess-Runbooks-1",
  "SpaceId": "Spaces-1"
}

Response

Created

CancelQueuedTasksboolean
CancelRunningTasksboolean
DefaultGuidedFailureMode'EnvironmentDefault' | 'Off' | 'On'
Descriptionstring
Environmentsstring[]
EnvironmentScope'All' | 'Specified' | 'FromProjectLifecycles'
FailTargetDiscoveryboolean
ForcePackageDownloadboolean
Idstring

Gets or sets a unique identifier for this resource.

LastModifiedBystring

Gets or sets the username of the user who last modified this resource.

LastModifiedOnstring date-time

Gets or sets the date/time that this resource was last modified.

Linksobject

Gets or sets a dictionary of links to other related resources. These links can be used to navigate the resources on the server.

MultiTenancyMode'Untenanted' | 'TenantedOrUntenanted' | 'Tenanted'
Namestring
ProjectIdstring
PublishedRunbookSnapshotIdstring
RunbookProcessIdstring
RunbookTagsstring[]

List of tags assigned to this runbook

Slugstring
SpaceIdstring

Example response

{
  "Environments": [
    "Environments-1",
    "..."
  ],
  "ProjectId": "Projects-1",
  "SpaceId": "Spaces-1"
}

Changes

No recorded changes to this endpoint across all 7 revisions of this API.