Runbooks

Update an existing Runbook

put/runbooks/{id}

Request

  • Base URL
    https://demo.octopus.app/api
  • URL
    https://demo.octopus.app/api/runbooks/{id}
  • Auth
    • API key in header X-Octopus-ApiKey
    • or API key in query parameter ApiKey
    • or API key in header X-NuGet-ApiKey

Path parameters

idstring required

The ID of the runbook to update, for example 'Runbooks-123'.

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.

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.

Idstring required

The ID of the runbook to update, for example 'Runbooks-123'.

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 project that stores its runbooks in the Octopus database.

PublishedRunbookSnapshotIdstring

The ID of the runbook snapshot to publish. Setting this to a different snapshot publishes that snapshot, which is what subsequent runs execute. Resubmit the current value to leave the published snapshot alone.

RunbookProcessIdstring

Leave this as the value returned when fetching the 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. Find the tag sets first to discover which ones 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",
    "..."
  ],
  "Links": {
    "Self": "/api/..."
  },
  "ProjectId": "Projects-1",
  "SpaceId": "Spaces-1"
}

Changes

No recorded changes to this operation across all 13 revisions of this API.