Runbooks

Run the published version of this Runbook

post/runbooks/{runbookId}/run

Request

  • Base URL
    https://demo.octopus.app/api
  • URL
    https://demo.octopus.app/api/runbooks/{runbookId}/run
  • 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

runbookIdstring required

ID of the runbook to run

Request body

Commentsstring

Any additional information/context

DebugModestring

If set to true contributes the OctopusPrintVariables and OctopusPrintEvaluatedVariables variables to the runbook run

EnvironmentIdstring

Legacy single-environment field; prefer EnvironmentIds. If set, this environment is added to the ones the runbook runs in. At least one of EnvironmentIds or EnvironmentId is required.

EnvironmentIdsstring[]

The environments to run the runbook in — the preferred way to specify targets, one run per environment. At least one of EnvironmentIds or EnvironmentId is required.

ExcludedMachineIdsstring[]

A collection of machines in the target environment that should be excluded from the runbook run.

ExcludedTargetTagIdsstring[]

A collection of target tag IDs that should be excluded from the deployment. Only deployment targets that have none of these tags will be deployed to. Tag IDs are in the format "TagSets-{id}/Tags-{id}".

FailTargetDiscoveryboolean

Whether to skip or fail cloud discovery steps with no matching target (default false).

ForcePackageDownloadboolean

Whether to force downloading of already installed packages (flag, default false).

FormValuesobject

Variables

Prioritystring
ProjectIdstring

ID of the project that the runbook belongs to

QueueTimestring date-time

The time to execute the runbook run

QueueTimeExpirystring date-time

The time at which the runbook run will timeout if it has not started executing.

RunbookIdstring required

ID of the runbook to run

RunbookSnapshotNameOrIdstring

Name or ID of a specific snapshot to run. Leave unset to run the published snapshot; when you set this, also set UseDefaultSnapshot to false.

SkipActionsstring[]

Actions that are to be skipped for this runbook.

SpaceIdstring required

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

SpecificMachineIdsstring[]

A collection of machines in the target environment that the runbook should be run on. If the collection is empty, all enabled machines are used.

SpecificTargetTagIdsstring[]

A collection of target tag IDs that should be included in the deployment. Only deployment targets that have at least one of these tags will be deployed to. Tag IDs are in the format "TagSets-{id}/Tags-{id}".

TenantIdstring

Legacy single-tenant field; prefer TenantIds. If set, this tenant is added to the ones the runbook runs for.

TenantIdsstring[]

The tenants to run the runbook for — the preferred way to specify tenants, creating one run per environment/tenant combination. Leave empty for an untenanted run.

TenantTagNamesstring[]

The tenant tags to filter tenants to run the runbook.

UseDefaultSnapshotboolean

Whether to run the runbook's published (default) snapshot. Leave true to run the published snapshot; set to false when you name a specific snapshot in RunbookSnapshotNameOrId.

UseGuidedFailureboolean

If set to true, the runbook will prompt for manual intervention (Fail/Retry/Ignore) when failures are encountered in activities that support it. May be overridden with the Octopus.UseGuidedFailure special variable.

Example request

{
  "EnvironmentId": "Environments-1",
  "EnvironmentIds": [
    "Environments-1",
    "..."
  ],
  "ProjectId": "Projects-1",
  "RunbookId": "Runbooks-1",
  "SpaceId": "Spaces-1",
  "TenantId": "Tenants-1",
  "TenantIds": [
    "Tenants-1",
    "..."
  ]
}

Response

OK

Changes

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