---
title: "Update an existing Runbook"
method: PUT
path: "/projects/{projectId}/{gitRef}/runbooks/{id}"
tags: ["Runbooks"]
---

# Update an existing Runbook

`PUT /projects/{projectId}/{gitRef}/runbooks/{id}`

## Path parameters

- `projectId` string, required
- `gitRef` string, required
- `id` string, required

## Request body

- ModifyRunbookInGitCommand
  - `CancelQueuedTasks` boolean — 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.
  - `CancelRunningTasks` boolean — 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.
  - `ChangeDescription` string — The commit message for the change. Defaults to 'Update runbook' when omitted.
  - `ConnectivityPolicy` DeploymentConnectivityPolicy
    - `AllowDeploymentsToNoTargets` boolean
    - `ExcludeUnhealthyTargets` boolean
    - `SkipMachineBehavior` 'None' | 'SkipUnavailableMachines'
    - `TargetRoles` string[]
  - `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.
  - `Description` string
  - `Environments` string[] — 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.
  - `FailTargetDiscovery` boolean — 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.
  - `ForcePackageDownload` boolean — Re-download every package on each run instead of reusing the copy already cached on the deployment target. Resets to false when omitted.
  - `GitRef` string, 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.
  - `Id` string, 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.
  - `Name` string, required
  - `ProjectId` string, required — The ID of the project the runbook belongs to. Must be a version-controlled project that stores its runbooks in Git.
  - `PublishedRunbookSnapshotId` string — The ID of the runbook snapshot to publish. Resubmit the current value to leave the published snapshot alone.
  - `RunbookProcessId` string — Leave this as the value returned by get_runbook. Octopus manages the link between a runbook and its process.
  - `RunbookTags` string[] — 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.
  - `RunRetentionPolicy` RunbookRetentionPolicy, required
    - `QuantityToKeep` integer
    - `ShouldKeepForever` boolean
    - `Strategy` string
    - `Unit` 'Days' | 'Items'
  - `Slug` string — A short URL-friendly identifier for the runbook, unique within the project. The current slug is kept when omitted.
  - `SpaceId` string, required

## Response `200`

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

- RunbookResource
  - `CancelQueuedTasks` boolean
  - `CancelRunningTasks` boolean
  - `ConnectivityPolicy` DeploymentConnectivityPolicy
    - `AllowDeploymentsToNoTargets` boolean
    - `ExcludeUnhealthyTargets` boolean
    - `SkipMachineBehavior` 'None' | 'SkipUnavailableMachines'
    - `TargetRoles` string[]
  - `DefaultGuidedFailureMode` 'EnvironmentDefault' | 'Off' | 'On'
  - `Description` string
  - `Environments` string[]
  - `EnvironmentScope` 'All' | 'Specified' | 'FromProjectLifecycles'
  - `FailTargetDiscovery` boolean
  - `ForcePackageDownload` boolean
  - `Id` string — Gets or sets a unique identifier for this resource.
  - `LastModifiedBy` string — Gets or sets the username of the user who last modified this resource.
  - `LastModifiedOn` string, date-time — Gets or sets the date/time that this resource was last modified.
  - `Links` object — 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'
  - `Name` string
  - `ProjectId` string
  - `PublishedRunbookSnapshotId` string
  - `RunbookProcessId` string
  - `RunbookTags` string[] — List of tags assigned to this runbook
  - `RunRetentionPolicy` RunbookRetentionPolicy
    - `QuantityToKeep` integer
    - `ShouldKeepForever` boolean
    - `Strategy` string
    - `Unit` 'Days' | 'Items'
  - `Slug` string
  - `SpaceId` string

## Other responses

- `400` — Bad request. Either the payload was not structurally valid or business rules did not permit the operation.
- `404` — Not found. One or more of the entities involved in the operation was not found.

---

[API](https://skmtc.net/octopus/apis/octopus-server-api.md) · [All operations](https://skmtc.net/octopus/apis/octopus-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/octopus/octopus-server-api/revisions/b296c3a60aa5/schema)