[rhysparry]

Background

OctopusDeploy/OctopusDeploy#49421 adds an AI agent access setting to runbooks (LEV-2060). Runbook authors can use the setting to stop AI agents from running a runbook. The docs don't cover the setting yet.

Results

The main section sits under Environments on the Runbooks vs Deployments page. That page already documents the other runbook run settings. A screenshot shows the setting's 2 options: agents allowed (the default) or blocked.

The section explains:

• Which runs count as agent runs. Runs from an agent API key or an agent service account count. Webhook triggers called with an agent API key also count. Scheduled triggers and shared-secret webhook triggers don't.
• What happens when a runbook is blocked. Octopus rejects agent runs, and agents see no environments for the runbook.
• That agents can block a runbook but can't unblock it.
• The AgentAccess API property, and that leaving it out keeps the current value.
• That the control is advisory, with its known limitations in a warning.

Short cross-links point to the setting from these pages:

• Config as Code runbooks, which explains the setting can differ between branches and commits
• Runbook permissions
• Webhook runbook triggers
• Agent service accounts
• Remote MCP and its use cases

How to review this PR

• The known limitations warning. It lists the ways agents can get around the setting. Please check we're happy to publish these limitations.
• Level of detail. The section leaves out the exact error messages and OCL format. The UI and the error messages cover those.

Reducing risk

• Wording checked against the server and UI code in OctopusDeploy/OctopusDeploy#49421
• The Version notes entry has a placeholder for the release version. Don't merge until #49421 ships and the placeholder has the real version.

🤖 Generated with Claude Code

🤖 Agent's description, endorsed by Rhys

[rhysparry]

Inline notes from Rhys. Each comment shows which parts were drafted by an AI agent.

[rhysparry]

🤖 Agent's comment, endorsed by Rhys

This placeholder needs the self-hosted Octopus Server version that ships agent access. The version comes from OctopusDeploy/OctopusDeploy#48864 once it merges and lands in a release.

The version notes standard asks for the exact version string, including the build number and trailing +. Please don't merge this PR until the placeholder has the real version.

Rhys: This MUST be resolved before merging.

[rhysparry]

🤖 Agent's comment, endorsed by Rhys

Still applies, but the version now comes from OctopusDeploy/OctopusDeploy#49421 rather than #48864. The placeholder in Version notes is updated to match. Don't merge until #49421 ships and the placeholder has the real version.

[team-marketing-branch-protections]

Pull request environment is available at https://stoctodocspr3522.z22.web.core.windows.net/.

You can view the ephemeral environment status in Octopus Deploy.

This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity.

[LukeButters]

I think this has the implication of "because then the agent could edit the book to allow it to run the runbook".

Perhaps it is worth calling that out explicitly, actually the UI should probably tell us that. That is if I select agents can't run this BUT agents can edit the runbook it perhaps ought to complain.

[rhysparry]

It's more convoluted than that. Agents can't change this setting in the runbook, but if they can edit or create runbooks, they could ignore the blocked runbook entirely and recreate the necessary process in another runbook they are allowed to run.

[LukeButters]

I assume this is done before the merge