Runbooks

Update an existing Runbook

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

Request

Base URL
https://demo.octopus.app/api
URL
https://demo.octopus.app/api/spaces/{spaceIdentifier}/projects/{projectId}/{gitRef}/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

spaceIdentifierstring required

Identifier (ID or slug) of the space

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 where the runbook is stored.

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. Find the project's branches first to see the valid values.

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 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.