diff --git a/public/docs/img/runbooks/runbooks-vs-deployments/runbook-runsettings-ai-agent-access.png b/public/docs/img/runbooks/runbooks-vs-deployments/runbook-runsettings-ai-agent-access.png new file mode 100644 index 0000000000..3fa7a8d399 Binary files /dev/null and b/public/docs/img/runbooks/runbooks-vs-deployments/runbook-runsettings-ai-agent-access.png differ diff --git a/src/pages/docs/octopus-ai/mcp/remote/index.md b/src/pages/docs/octopus-ai/mcp/remote/index.md index f245e8d7c4..8273bf8daf 100644 --- a/src/pages/docs/octopus-ai/mcp/remote/index.md +++ b/src/pages/docs/octopus-ai/mcp/remote/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2026-08-17 -modDate: 2026-10-20 +modDate: 2026-10-26 title: Octopus Remote MCP navTitle: Remote MCP navSection: Octopus Remote MCP @@ -191,6 +191,8 @@ We plan to add OAuth authentication in a future release. Until then, AI assistan Octopus Remote MCP uses the same security boundary as the Octopus REST API. Permissions for the user or service account that owns the API key apply in the same way. +To stop agents from running a runbook, use the runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting. The MCP server returns no environments for a blocked runbook, so agents don't try runs that would fail. + ## Turn off Remote MCP To turn off Remote MCP, go to **Configuration > Settings > MCP Controls**. Clear the **Enable Remote MCP** checkbox, then select **Save**. diff --git a/src/pages/docs/octopus-ai/mcp/remote/use-cases.md b/src/pages/docs/octopus-ai/mcp/remote/use-cases.md index 00f65f5410..7fda98d936 100644 --- a/src/pages/docs/octopus-ai/mcp/remote/use-cases.md +++ b/src/pages/docs/octopus-ai/mcp/remote/use-cases.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2026-08-17 -modDate: 2026-08-17 +modDate: 2026-10-26 title: Octopus Remote MCP use cases navTitle: Use cases description: Explore how Octopus Remote MCP helps teams track releases, diagnose failures, automate deployments, audit changes, and manage tenants. @@ -43,7 +43,7 @@ Example prompts: - "Generate release notes for release 2.4.1 and attach them to the release." - "Run the Restart payment workers runbook in Production." -Operations that make changes run with the permissions of the API key used to connect the assistant. Use a dedicated [Agent Service Account](/docs/security/users-and-teams/service-accounts#agent-service-accounts) and grant it only the permissions it needs. +Operations that make changes run with the permissions of the API key used to connect the assistant. Use a dedicated [Agent Service Account](/docs/security/users-and-teams/service-accounts#agent-service-accounts) and grant it only the permissions it needs. To stop agents from running a sensitive runbook, use the runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting. ## Operational oversight diff --git a/src/pages/docs/runbooks/config-as-code-runbooks.md b/src/pages/docs/runbooks/config-as-code-runbooks.md index 3a25131cbd..7a775c8497 100644 --- a/src/pages/docs/runbooks/config-as-code-runbooks.md +++ b/src/pages/docs/runbooks/config-as-code-runbooks.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2024-11-24 -modDate: 2026-10-13 +modDate: 2026-10-26 title: Config as Code runbooks description: Details about using configuration as code with runbooks. navOrder: 20 @@ -83,6 +83,12 @@ Assuming your default branch is protected, this means that your old 'published' 💡 If you are using Octopus's built in roles, keep these permissions in mind when moving your draft runbooks out of the 'migrated-drafts/' folder and consider storing these runbooks on a non-default branch. +## AI agent access + +A runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting is stored in its OCL file, so it can differ between branches and commits. Octopus only writes `agent_access` to the file when the runbook blocks agents, so saving a runbook that lets agents run it doesn't change its OCL file. + +When an AI agent runs a Config as Code runbook, Octopus checks the setting in the version being run. An agent can still run a blocked runbook from a branch, tag, or commit where the setting lets agents run it. Protect your default branch so changes to the setting go through your usual review process. + ## Snapshots vs commits Another exciting thing about CaC Runbooks is that every revision to your runbook process, settings and variables is captured in your commit history. This means that you can now re-run any previous version of your runbook without the need for snapshots. diff --git a/src/pages/docs/runbooks/runbook-permissions/index.md b/src/pages/docs/runbooks/runbook-permissions/index.md index 136ef9cd12..d53f7f69d2 100644 --- a/src/pages/docs/runbooks/runbook-permissions/index.md +++ b/src/pages/docs/runbooks/runbook-permissions/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2026-08-17 +modDate: 2026-10-26 title: Runbooks permissions description: Permissions are available to help you manage access to Runbooks. navOrder: 20 @@ -25,6 +25,10 @@ Permissions are available to help you manage access to Runbooks, these include: You can limit your teams ability to create runbooks by disabling these permissions. +:::div{.hint} +To stop AI agents from running a runbook, use the runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting. It works alongside these permissions and only restricts agents. +::: + There are roles we include out-of-the-box to encapsulate these new permissions: | Role | Description | diff --git a/src/pages/docs/runbooks/runbooks-vs-deployments/index.md b/src/pages/docs/runbooks/runbooks-vs-deployments/index.md index 69497ae924..e605fd4f49 100644 --- a/src/pages/docs/runbooks/runbooks-vs-deployments/index.md +++ b/src/pages/docs/runbooks/runbooks-vs-deployments/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2023-10-04 +modDate: 2026-10-26 title: Runbooks vs Deployments description: Describing the differences between a deployment and a runbook. navOrder: 10 @@ -34,7 +34,7 @@ A [project's variables](/docs/projects/variables) are shared between the deploym In Octopus 2020.2 and earlier, runbooks could be executed against any environment for which the user had an appropriately scoped `RunbookRunCreate` permission. -From **Octopus 2020.3**, it's also possible to choose which environments a runbook can be run in by selecting this from the *Run settings* in **Runbook ➜ Settings**: +From **Octopus 2020.3**, it's also possible to choose which environments a runbook can be run in by selecting this from the *Run Settings* in **Runbook ➜ Settings**: :::figure ![Runbook environments choice](/docs/img/runbooks/runbooks-vs-deployments/runbook-runsettings-environments.png) @@ -50,9 +50,43 @@ You can select the runbook to run in: In Octopus 2020.2 and earlier, if you need to restrict the environment that a runbook can be executed in, you can achieve this by adding an [Environment run condition](/docs/projects/steps/conditions/#environments) in each step of the runbook process. ::: +### AI agent access + +AI agent access controls whether AI agents can run a runbook. Use it to keep agents away from sensitive runbooks, such as ones that change production infrastructure, while still letting them run routine ones. + +The setting sits below **Environments** in the *Run Settings* of **Runbook ➜ Settings**: + +:::figure +![The AI agent access setting on the runbook settings page, with the options AI agents can run this runbook and AI agents can't run this runbook](/docs/img/runbooks/runbooks-vs-deployments/runbook-runsettings-ai-agent-access.png) +::: + +You can choose: + +- **AI agents can run this runbook** (the default) +- **AI agents can't run this runbook** + +Blocking only applies to runs started with an AI agent's credentials: an [agent API key](/docs/api/authentication/create-an-api-key#creating-an-agent-api-key) or an [agent service account](/docs/security/users-and-teams/service-accounts#agent-service-accounts). This includes agents using the [Octopus MCP server](/docs/octopus-ai/mcp), and [webhook triggers](/docs/runbooks/webhook-runbook-trigger#authentication) called with an agent API key. Runs started by users, scheduled triggers, and webhook triggers that use a shared secret aren't affected. + +When a runbook is blocked, Octopus rejects an agent's run with an error before the run starts. Agents also see an empty list of environments for the runbook, so they don't try runs that would fail. + +AI agent access adds to [runbook permissions](/docs/runbooks/runbook-permissions) rather than replacing them. + +Agents can change the setting to block themselves, but they can't change it back. To let agents run it again, a user or a non-agent service account needs to change the setting. In the API, the setting is the runbook's `AgentAccess` property, set to `Allowed` or `Blocked`. If you leave `AgentAccess` out when you modify a runbook, Octopus keeps its current value. + +:::div{.warning} +AI agent access is an advisory control. It stops agents from running a runbook directly, but it isn't a security boundary. Agents can get around it: + +- An agent that can edit the runbook can still change its other settings, such as its environments. +- An agent can create a [scheduled trigger](/docs/runbooks/scheduled-runbook-trigger) or a shared-secret [webhook trigger](/docs/runbooks/webhook-runbook-trigger) that runs the runbook. These runs use the Octopus system user, so they aren't blocked. +- Octopus checks the setting when it creates a run. Runs an agent queued before the runbook was blocked still start, including runs scheduled for later. +- For [Config as Code runbooks](/docs/runbooks/config-as-code-runbooks#ai-agent-access), an agent can run from a branch or commit where the setting still lets agents run the runbook. + +For runbooks you want to protect, don't give agents permission to edit runbooks (`RunbookEdit`) or triggers (`TriggerCreate` and `TriggerEdit`). +::: + ## Retention policy -Project [Lifecycles](/docs/releases/lifecycles) and their retention policies do not apply to runbooks (only deployments). From **Octopus 2020.3**, it's possible to set a retention policy for a runbook by selecting this from the *Run settings* in **Runbook ➜ Settings**: +Project [Lifecycles](/docs/releases/lifecycles) and their retention policies do not apply to runbooks (only deployments). From **Octopus 2020.3**, it's possible to set a retention policy for a runbook by selecting this from the *Run Settings* in **Runbook ➜ Settings**: :::figure ![Runbook retention policies](/docs/img/runbooks/runbooks-vs-deployments/runbook-runsettings-retention.png) @@ -86,3 +120,7 @@ Runbooks are similar to deployments in that they also take a copy of the process **Package versions are included in a snapshot** Similar to releases, the version of any packages that are used in the runbook are also snapshotted. This means if a newer version of the package is uploaded, and you wish to use it in your runbook, you will need to create a new snapshot of the runbook. ::: + +## Version notes + +- AI agent access for runbooks is available from Octopus **2026.4.9164**. diff --git a/src/pages/docs/runbooks/webhook-runbook-trigger/index.md b/src/pages/docs/runbooks/webhook-runbook-trigger/index.md index 97cb5b7a32..11c12e36ca 100644 --- a/src/pages/docs/runbooks/webhook-runbook-trigger/index.md +++ b/src/pages/docs/runbooks/webhook-runbook-trigger/index.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2026-08-06 -modDate: 2026-08-06 +modDate: 2026-10-26 title: Webhook runbook triggers description: Webhook runbook triggers let an external system run a runbook by sending an HTTP request to Octopus. navOrder: 45 @@ -116,6 +116,7 @@ The runbook run is created as the owner of the API key, which means: - The key's owner needs the `RunbookRunCreate` [permission](/docs/runbooks/runbook-permissions) for the project, and for every environment and tenant the trigger targets. - The run appears in the audit log and task list as being run by that user, rather than by the Octopus system user. +- If the key is an [agent API key](/docs/api/authentication/create-an-api-key#creating-an-agent-api-key), or belongs to an agent service account, the run is an agent run, and the runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting applies. We recommend using a [service account](/docs/security/users-and-teams/service-accounts) scoped to only what the runbook needs, rather than a key belonging to a person. diff --git a/src/pages/docs/security/users-and-teams/service-accounts.md b/src/pages/docs/security/users-and-teams/service-accounts.md index fb7834a494..eb709d2d54 100644 --- a/src/pages/docs/security/users-and-teams/service-accounts.md +++ b/src/pages/docs/security/users-and-teams/service-accounts.md @@ -1,7 +1,7 @@ --- layout: src/layouts/Default.astro pubDate: 2023-01-01 -modDate: 2026-06-19 +modDate: 2026-10-26 title: Service accounts description: Creating Service Accounts to provide individual services with the least privileges required for the tasks they will perform. navOrder: 2 @@ -56,7 +56,7 @@ Once you have created an [Octopus API key](/docs/api/authentication/create-an-ap If you're connecting an AI agent to Octopus—such as the [Octopus MCP server](/docs/octopus-ai/mcp) or any other automated tooling that runs without a human user session—create an **Agent Service Account** rather than a regular service account. Agent service accounts are a dedicated identity type for AI agents, and they're labeled as such across the product, making agent activity easy to identify and audit. -Any API key created under an agent service account is automatically treated as an agent key. This means you can filter for agent activity separately from human activity in the [audit log](/docs/security/users-and-teams/auditing) and on the **API Keys** page. +Any API key created under an agent service account is automatically treated as an agent key. This means you can filter for agent activity separately from human activity in the [audit log](/docs/security/users-and-teams/auditing) and on the **API Keys** page. It also means a runbook's [AI agent access](/docs/runbooks/runbooks-vs-deployments#ai-agent-access) setting applies to any runbook run the account starts. To create an agent service account: