Sign in
Runbooks

Update an existing Runbook

put/projects/{projectId}/{gitRef}/runbooks/{id}

Path parameters

projectIdstring required

The ID of the project the runbook belongs to. Must be a version-controlled project that stores its runbooks in Git.

gitRefstring required

The Git branch to commit the change to. This must be a branch — a tag or commit cannot be written to — and the branch must not be protected in the project's version control settings. Use get_branches to list the project's branches.

idstring required

The ID of the runbook to update. A runbook stored in Git uses its slug as the ID, which is only unique within its project and Git ref.

Request body

CancelQueuedTasksboolean

When a new run of this runbook is queued, automatically cancel earlier runs of it that are still queued and now superseded. This is a standing setting on the runbook, not an instruction to cancel anything right now. Omit to leave the current setting unchanged.

CancelRunningTasksboolean

When a new run of this runbook is queued, automatically cancel an earlier run of it that is already executing and now superseded. This is a standing setting on the runbook, not an instruction to cancel anything right now. Omit to leave the current setting unchanged.

ChangeDescriptionstring

The commit message for the change. Defaults to 'Update runbook' when omitted.

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), or 'On' (pause the run and wait for someone to choose whether to retry, ignore or abort). Resets to 'Off' when omitted.

Descriptionstring
Environmentsstring[]

The runbook's complete environment list, used when EnvironmentScope is 'Specified'. This replaces the current list, so resubmit the existing environments you want to keep. The update is rejected if it would remove an environment that a project trigger still runs this runbook in.

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

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

FailTargetDiscoveryboolean

Fail a run when one of its target discovery steps finds no matching deployment targets, instead of letting the step succeed. Resets to false when omitted.

ForcePackageDownloadboolean

Re-download every package on each run instead of reusing the copy already cached on the deployment target. Resets to false when omitted.

GitRefstring required

The Git branch to commit the change to. This must be a branch — a tag or commit cannot be written to — and the branch must not be protected in the project's version control settings. Use get_branches to list the project's branches.

Idstring required

The ID of the runbook to update. A runbook stored in Git uses its slug as the ID, which is only unique within its project and Git ref.

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

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

Namestring required
ProjectIdstring required

The ID of the project the runbook belongs to. Must be a version-controlled project that stores its runbooks in Git.

PublishedRunbookSnapshotIdstring

The ID of the runbook snapshot to publish. Resubmit the current value to leave the published snapshot alone.

RunbookProcessIdstring

Leave this as the value returned by get_runbook. Octopus manages the link between a runbook and its process.

RunbookTagsstring[]

The runbook's complete set of tags, each written as "TagSet/Tag" using either the names or the IDs of the tag set and tag (for example "Ops/Nightly"). This replaces the current tags, so resubmit the existing ones you want to keep. Call find_tag_sets to discover which tag sets apply to runbooks.

Slugstring

A short URL-friendly identifier for the runbook, unique within the project. The current slug is kept when omitted.

SpaceIdstring required

Example request

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

Response

Confirmation that the Runbook has been modified, containing the updated Runbook

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