User roles

User roles and group permissions play a major part in the Octopus security model. These roles are assigned to Teams and they dictate what the members of those teams can do in Octopus.

Built-in user roles

Octopus comes with a set of built-in user roles that are designed to work for most common scenarios:

User roleDescription
Build ServerBuild servers can publish packages, and create releases, deployments, runbook snapshots and runbook runs.
Certificate ManagerCertificate managers can edit certificates and export private-keys
Deployment CreatorDeployment creators can create new deployments and runbook runs.
Environment ManagerEnvironment managers can view and edit environments and their machines.
Environment ViewerEnvironment viewers can view environments and their machines, but not edit them.
Package PublisherPermits packages to be pushed to the Octopus Server’s built-in NuGet feed.
Project ViewerProject 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 ContributorAll project viewer permissions, plus: editing and viewing variables, editing the deployment steps. Project contributors can’t create or deploy releases.
Project InitiatorAll project viewer permissions, plus: create new projects.
Project DeployerAll project contributor permissions, plus: deploying releases, but not creating them.
Project LeadAll project contributor permissions, plus: creating releases, but not deploying them.
Release CreatorRelease creators can create new releases and runbook snapshots.
Runbook ConsumerRunbook consumers can view and execute runbooks.
Runbook ProducerRunbook producers can edit and execute runbooks.
System AdministratorSystem administrators can do everything at the system level.
System ManagerSystem managers can do everything at the system level except certain system-level functions reserved for system administrators.
Tenant ManagerTenant managers can edit tenants and their tags

The built-in user roles can be modified to contain more or less roles to suit specific needs. But instead of modifying the built-in ones, we recommend that you leave them as an example and instead create your own user roles.

To view the default permissions for each of the built-in user roles, please see default permissions.

Additional user roles for spaces

User RoleDescription
Space ManagerSpace managers can do everything within the context of the space they own.

For more information regarding the system or space level, please see system and space permissions.

Creating user roles

A custom User Role can be created with any combination of permissions. To create a custom user role:

  1. Under the Configuration page, click Roles.

  2. Click Add custom role.

  3. Select the set of permissions you’d like this new User Role to contain, and give the role a name and description. These can be system or space level permissions.

Once the custom role is saved, the new role will be available to be assigned to teams in Octopus. Some rules apply, depending on the mix of system or space level permissions you chose.

When applying roles to a team, you can optionally specify a scope for each role applied. This enables some complex scenarios, like granting a team different levels of access based on the environment they are authorized for.

Troubleshooting permissions

If for some reason a user has more/fewer permissions than they should, you can use the Test Permissions feature to get an easy to read list of all the permissions that a specific user has on the Octopus instance.

To test the permissions go to Configuration ➜ Test Permissions and select a user from the drop-down.

The results will show:

  • The teams of which the user is a member of. There are two separate Permission context that you can check.
  • A chart detailing each role and on which Environment/Project this permission can be executed. The chart can be exported to a CSV file by clicking the Export button. Once the file is downloaded it can viewed in browser using Online CSV Editor and Viewer.

If a user tries to perform an action without having enough permissions to do it, an error message will pop up showing which permissions the user is lacking, and which teams actually have these permissions.

As further versions of Octopus are released, we might create new roles to improve our security model. These new roles will not be automatically included in any of the built-in user roles, to avoid giving users permissions they are not supposed to have. These new roles will have to be added manually to a User Role by an administrator.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Sunday, January 1, 2023