Skip to content

Update docs with new RunbookSnapshotCreate permission #3346

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
grace-rehn wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Update docs with new RunbookSnapshotCreate permission #3346

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9e5c808
Update docs with new RunbookSnapshotCreate permission
grace-rehn Aug 12, 2026
12ef8ab
Lint
grace-rehn Aug 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 35 additions & 32 deletions src/pages/docs/best-practices/octopus-administration/users-roles-and-teams.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2023-10-04
modDate: 2026-08-12
title: Users, Roles, and Teams
description: Guidelines and recommendations for managing RBAC in Octopus Deploy.
navOrder: 80
Expand All @@ -13,6 +13,7 @@ A [user](/docs/security/users-and-teams/) is an entity that performs an action i
A user can be directly or indirectly associated with a team. You can explicitly assign a user to a team. Or you can assign teams from [external auth providers](/docs/security/authentication) to Octopus Deploy teams.

There are two kinds of users in Octopus Deploy:

- User Account: allowed to log in to both the Octopus Web Portal and Octopus API. Can be authenticated with external auth providers, username and password, or an Octopus API Key.
- [Service Accounts](/docs/security/users-and-teams/service-accounts) are API-only accounts used for automated services that integrate with Octopus Deploy. It can only be authenticated with an Octopus API Key.

Expand All @@ -36,39 +37,41 @@ We also recommend creating a unique service account per integration. For exampl
**Octopus Deploy 2020.6** introduced the concept of expiring API keys. Our recommendation is to set up a periodic rotation of API keys following your companies policy on key expiration.

If your company doesn't already have a policy, then our recommendation is:

- 90 days for service accounts. In other words, rotate the service account keys once a quarter.
- 10-30 days for users. User account API keys should be used temporarily when writing an API script or testing an integration.

## User Roles

Octopus Deploy includes several built-in roles:

| User role | Description |
| -------------------- | ---------------------------------------- |
| Build Server | Build servers can publish packages, and create releases, deployments, runbook snapshots and runbook runs. |
| Certificate Manager | Certificate managers can edit certificates and export private-keys |
| Deployment Creator | Deployment creators can create new deployments and runbook runs. |
| <span class="nowrap">Environment Manager</span> | Environment managers can view and edit environments and their machines. |
| Environment Viewer | Environment viewers can view environments and their machines, but not edit them. |
| Package Publisher | Permits packages to be pushed to the Octopus Server's built-in NuGet feed. |
| Project Viewer | Project viewers have read-only access to a project. They can see a project in their dashboard, view releases and deployments. Restrict this role by project to limit it to a subset of projects, and restrict it by environment to limit which environments they can view deployments to. |
| Project Contributor | All project viewer permissions, plus: editing and viewing variables, editing the deployment steps. Project contributors can't create or deploy releases. |
| Project Initiator | All project viewer permissions, plus: create new projects. |
| Project Deployer | All project contributor permissions, plus: deploying releases, but not creating them. |
| Project Lead | All project contributor permissions, plus: creating releases, but not deploying them. |
| Release Creator | Release creators can create new releases and runbook snapshots. |
| Runbook Consumer | Runbook consumers can view and execute runbooks. |
| Runbook Producer | Runbook producers can edit and execute runbooks. |
| Space Managers | Space managers can do everything within the context of the space they own. |
| System Administrator | System administrators can do everything at the system level. |
| System Manager | System managers can do everything at the system level except certain system-level functions reserved for system administrators. |
| Tenant Manager | Tenant managers can edit tenants and their tags |
| User role | Description |
| --- | --- |
| Build Server | Build servers can publish packages, and create releases, deployments, runbook snapshots and runbook runs. They can't edit a runbook's steps or publish its snapshots. |
| Certificate Manager | Certificate managers can edit certificates and export private-keys |
| Deployment Creator | Deployment creators can create new deployments and runbook runs. |
| <span class="nowrap">Environment Manager</span> | Environment managers can view and edit environments and their machines. |
| Environment Viewer | Environment viewers can view environments and their machines, but not edit them. |
| Package Publisher | Permits packages to be pushed to the Octopus Server's built-in NuGet feed. |
| Project Viewer | Project viewers have read-only access to a project. They can see a project in their dashboard, view releases and deployments. Restrict this role by project to limit it to a subset of projects, and restrict it by environment to limit which environments they can view deployments to. |
| Project Contributor | All project viewer permissions, plus: editing and viewing variables, editing the deployment steps. Project contributors can't create or deploy releases. |
| Project Initiator | All project viewer permissions, plus: create new projects. |
| Project Deployer | All project contributor permissions, plus: deploying releases, but not creating them. |
| Project Lead | All project contributor permissions, plus: creating releases, but not deploying them. |
| Release Creator | Release creators can create new releases and runbook snapshots. |
| Runbook Consumer | Runbook consumers can view and execute runbooks. |
| Runbook Producer | Runbook producers can edit and execute runbooks. |
| Space Managers | Space managers can do everything within the context of the space they own. |
| System Administrator | System administrators can do everything at the system level. |
| System Manager | System managers can do everything at the system level except certain system-level functions reserved for system administrators. |
| Tenant Manager | Tenant managers can edit tenants and their tags |

We recommend using the built-in roles as much as possible. When we write migration scripts or upgrade scripts that add additional permissions, we will ensure we update those built-in roles. Custom roles will be skipped, so we don't accidentally grant permissions.

## Teams

Octopus Deploy includes four built-in teams:

- Everyone
- Octopus Administrators
- Octopus Managers
Expand All @@ -83,20 +86,20 @@ Teams can either be a system team, meaning it can be used across all spaces, or
Here are some of the more common scenarios we get asked about, along with the associated user roles and scope. For this example, our instance has four environments, **development**, **test**, **staging**, and **production**.

- Developers have permissions to deploy to modify the deployment process and variables. Can deploy to the **development** and **test** environments.
- Add `Project Contributor` role to the Developers team, no scoping on environments or projects.
- Add `Release Creator` role to the Developers team, no scoping on environments or projects.
- Add `Environment Viewer` role to the Developers team, no scoping on environments or projects.
- Add `Deployment Creator` role to the Developers team, scope to **development** and **test** environments.
- Add `Project Contributor` role to the Developers team, no scoping on environments or projects.
- Add `Release Creator` role to the Developers team, no scoping on environments or projects.
- Add `Environment Viewer` role to the Developers team, no scoping on environments or projects.
- Add `Deployment Creator` role to the Developers team, scope to **development** and **test** environments.
- QA has permissions to deploy to **test** and **staging**, cannot modify anything in the project.
- Add `Deployment Creator` role to the QA team, scope to **test**, and **staging**.
- Add `Project Viewer` role to the QA team, no scoping on environment or projects.
- Add `Deployment Creator` role to the QA team, scope to **test**, and **staging**.
- Add `Project Viewer` role to the QA team, no scoping on environment or projects.
- Operations has permissions to deploy to **staging** and **production**, cannot modify the deployment process. They can add accounts, workers, and deployment targets.
- Add `Deployment Creator` role to the Operations team, scope to **test**, and **staging**.
- Add `Project Viewer` role to the Operations team, no scoping on environment or projects.
- Add `Environment Manager` role to the Operations team, no scoping on environment or projects.
- Add `Deployment Creator` role to the Operations team, scope to **test**, and **staging**.
- Add `Project Viewer` role to the Operations team, no scoping on environment or projects.
- Add `Environment Manager` role to the Operations team, no scoping on environment or projects.
- Project Owners can only approve deployments; they cannot modify or deploy them.
- Add `Project Viewer` role to the Project Owners team, no scoping on environment or projects.
- Add `Environment Viewer` role to the Project Owners team, no scoping on environment or projects.
- Add `Project Viewer` role to the Project Owners team, no scoping on environment or projects.
- Add `Environment Viewer` role to the Project Owners team, no scoping on environment or projects.

## Further reading

Expand Down
27 changes: 16 additions & 11 deletions src/pages/docs/runbooks/runbook-permissions/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,27 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2023-01-01
modDate: 2026-08-12
title: Runbooks permissions
description: Permissions are available to help you manage access to Runbooks.
navOrder: 20

---

:::div{.hint}
The `RunbookSnapshotCreate` permission is available from **Octopus 2026.3** onwards. Prior to this version, `RunbookEdit` covered creating snapshots.
:::

Permissions are available to help you manage access to Runbooks, these include:

| Permission | Description |
| Permission | Description |
| ------------- | ------------- |
| RunbookView | You can view all things runbooks-related (from the runbooks themselves, to their process, runs and snapshots). |
| RunbookEdit | You can edit all things runbooks-related. |
| RunbookRunView | You can view runbook runs. |
| RunbookRunDelete | You can delete runbook runs. |
| RunbookRunCreate | You can create runbook runs (equivalent of `DeploymentCreate` in the deployment world). |
| RunbookView | You can view all things runbooks-related (from the runbooks themselves, to their process, runs and snapshots). |
| RunbookEdit | You can edit a runbook's process, and publish or delete its snapshots. |
| RunbookSnapshotCreate | You can create runbook snapshots. |
| RunbookRunView | You can view runbook runs. |
| RunbookRunDelete | You can delete runbook runs. |
| RunbookRunCreate | You can create runbook runs (equivalent of `DeploymentCreate` in the deployment world). |

You can limit your teams ability to create runbooks by disabling these permissions.

Expand All @@ -32,10 +37,10 @@ There are roles we include out-of-the-box to encapsulate these new permissions:
Octopus Deploy is built API-first, which means everything you can do through the Octopus UI can be done with the API. In the API, we model the runbook and its process the same way, starting at the project:

- Project
- Runbooks _(a project can have many runbooks, with RunbookView/RunbookEdit permissions.)_
- RunbookProcess _(a runbook has one process / collection of steps, with ProcessEdit permissions.)_
- RunbookSnapshots _(a runbook can have many snapshots, each with a unique name, with RunbookEdit permissions.)_
- RunbookRuns _(a runbook snapshot will then be run/executed against an environment, with RunbookRunCreate permissions.)_
- Runbooks *(a project can have many runbooks, with RunbookView/RunbookEdit permissions.)*
- RunbookProcess *(a runbook has one process / collection of steps, with ProcessEdit permissions.)*
- RunbookSnapshots *(a runbook can have many snapshots, each with a unique name. Creating a snapshot needs RunbookSnapshotCreate, and publishing or deleting one needs RunbookEdit.)*
- RunbookRuns *(a runbook snapshot will then be run/executed against an environment, with RunbookRunCreate permissions.)*

We have provided lots of helpful functions for building your runbook process in the [.NET SDK](/docs/octopus-rest-api/octopus.client), or you can use the raw HTTP API if that suits your needs better.

Expand Down
21 changes: 13 additions & 8 deletions src/pages/docs/runbooks/runbook-publishing/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,22 @@
---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2023-01-01
modDate: 2026-08-12
title: Runbooks publishing
description: Publishing makes a runbook available to scheduled triggers and consumers.
navOrder: 30
---

:::div{.success}
Config-as-code runbooks use branches instead of publishing. If your project uses config-as-code runbooks, read about [managing runbooks permissions using branches](/docs/runbooks/config-as-code-runbooks#permissions-by-branch) instead.
Config-as-code runbooks use branches instead of publishing. If your project uses config-as-code runbooks, read about [managing runbooks permissions using branches](/docs/runbooks/config-as-code-runbooks#permissions-by-branch) instead.
:::

Runbooks and deployments define their processes in exactly the same way. However, where a deployment has a [release](/docs/releases), a runbook has what is called a Snapshot.
Runbooks and deployments define their processes in exactly the same way. However, where a deployment has a [release](/docs/releases), a runbook has what is called a Snapshot.

## Snapshots

For a given runbook, you can have two snapshots:

- Draft
- Published

Expand All @@ -26,16 +27,20 @@ Similar to releases, the version of any packages that are used in the runbook ar
A draft snapshot of a runbook is exactly what it sounds like, a draft version of the currently published version. Drafts are meant to give you a place to work and save a runbook that is a work in progress or has not yet been approved for general use.

:::div{.hint}
Draft snapshots can't be used to create a [scheduled runbook trigger](/docs/runbooks/scheduled-runbook-trigger), only published snapshots can.
Draft snapshots can't be used to create a [scheduled runbook trigger](/docs/runbooks/scheduled-runbook-trigger), only published snapshots can.
:::

## Published snapshot

The concept of a published snapshot is designed to help avoid confusion when selecting a version of the runbook you're supposed to run if you're not the author. You can think of it as the "Production" ready version of the runbook, which has been approved for general use.

Publishing makes a runbook available to scheduled triggers and consumers (anyone with an appropriately scoped `RunbookRunCreate` permission, but without the `RunbookEdit` permission). Triggers and consumers will always execute the published snapshot.
:::div{.hint}
The `RunbookSnapshotCreate` permission is available from **Octopus 2026.3** onwards. Prior to this version, `RunbookEdit` covered creating snapshots.
:::

Publishing makes a runbook available to scheduled triggers and consumers (anyone with an appropriately scoped `RunbookRunCreate` permission, but without the `RunbookSnapshotCreate` permission). Triggers and consumers will always execute the published snapshot.

The published snapshot contains the process, variables, and packages. This allows editing and testing the runbook without impacting the published version.
The published snapshot contains the process, variables, and packages. This allows editing and testing the runbook without impacting the published version.

### Publishing a snapshot

Expand All @@ -53,8 +58,8 @@ Publish from process:
![Publish runbook from process page](/docs/img/runbooks/runbook-publishing/runbook-publish-process.png)
:::

When a producer (anyone with an appropriately scoped `RunbookEdit` permission) executes a runbook, they will have the option between executing the published version or the current draft.
When a producer (anyone with an appropriately scoped `RunbookSnapshotCreate` permission) executes a runbook, they will have the option between executing the published version or the current draft.

Running the current draft allows testing changes before publishing. The latest version of the process and variables will be used and package versions will be prompted for.

![Run current draft](/docs/img/runbooks/runbook-publishing/runbook-run-draft.png)
![Run current draft](/docs/img/runbooks/runbook-publishing/runbook-run-draft.png)
Loading