When creating a service account, you choose whether to define it at the root level or at the item level (for example, within a specific folder or job). This decision determines what the service account can access and who can manage it.
Use root-scoped service accounts when you need centralized access across multiple controllers, such as for organization-wide monitoring or deployment Pipelines. Use item-scoped service accounts when you want teams to manage their own automation without requiring administrative access, keeping permissions limited to specific folders or projects.
Root-scoped service accounts
You can create root-scoped service accounts at the operations center or controller root level. Root-scoped service accounts are available across all controllers in the default configuration. You can add them to any groups. For details, refer to Service account behavior across operations center and controllers.
Item-scoped service accounts
You can create service accounts directly within an item, such as a folder, to provide more granular access control.
An item-scoped service account can only be added to groups defined on that item or its descendant jobs and folders. It cannot be added to groups defined at the root scope or to ancestor or sibling items.
Item-scoped identity and folder paths
The identity of an item-scoped service account includes the full path to the item; it is unrelated to any root-scoped service account with the same name. When an item-scoped service account is added to a group, the group membership encodes the full identity of the service account, including its folder path.
|
The folder path uses slashes ( |
|
Configure item-scoped permissions
You can grant permissions to item-scoped service accounts the same way as root-scoped service accounts, with one exception: item-scoped service accounts are automatically granted Overall/Read and Job/Read permissions on their containing item and parent folders. Otherwise, it would be impossible to even access the folder where it is defined, since it could not receive these permissions from any group defined at a higher scope. Any other permissions must be granted via group membership.
In particular, an item-scoped service account does not automatically receive the Job/Read permission on descendant jobs or folders; these must be granted explicitly via group membership.
Example: Define service account directly on a job
Scenario:
You want to create a service account specifically to trigger builds on the job my-team/dev/test.
Solution:
Define the service account directly on the my-team/dev/test job.
Add it to a group defined on that job with the Job/Build permission.
The service account automatically receives Job/Read permission on my-team, my-team/dev, and my-team/dev/test.
Example: Grant access to a specific subfolder
Scenario:
You have an existing service account defined for a folder named my-team.
You want to let it trigger builds in developer jobs such as my-team/dev/test, but not in any other jobs under my-team (such as my-team/prod/deploy).
Solution:
You need to create a group defined on my-team/dev with both the Job/Build and Job/Read permissions, and add the service account to that group.
Example: Grant access to a single job
Scenario:
You have an existing service account defined for a folder named my-team.
You want it to trigger builds only on one job my-team/dev/test, but not other jobs under my-team/dev.
Solution:
You need to add the service account to a group defined on my-team/dev with the Job/Read permission (propagated to descendants), and to another group defined on my-team/dev/test with the Job/Build permission.
| For a more restrictive approach that prevents the service account from listing other jobs, refer to Example: Lock down permissions further. |
Example: Lock down permissions further
Scenario:
You have an existing service account defined for a folder named my-team.
You want it to trigger builds only on one job my-team/dev/test, and you want to prevent it from even listing other jobs under my-team/dev.
Solution:
You need to add the service account to a group granting Job/Read permissions without propagation on my-team/dev, and to another group granting both Job/Build and Job/Read permissions on my-team/dev/test.
Service account behavior across operations center and controllers
Service accounts can be defined and used in the operations center at the root or item scope. By default, controllers inherit their authorization configuration from the operations center. If the operations center permits opt-out in its security configuration, a controller may opt out of this inheritance and define its own authorization strategy using any available plugin, including the CloudBees Role-Based Access Control plugin.
| When a controller opts out of authorization inheritance, there is no relationship between RBAC in the operations center and RBAC in the controller. A controller may also opt out of authentication inheritance, defining its own security realm rather than using the operations center’s single sign-on (SSO). |
| Service account definition location | Controller inherits authorization strategy from operations center | Controller opts out of the operations center authorization strategy |
|---|---|---|
Operations center root |
|
|
Operations center item |
|
|
Controller root |
|
|
Controller item |
|
|