permissions

Use the permissions field to maintain secure and efficient workflows in CloudBees. Control access to resources to minimize risk. Apply the Principle of Least Privilege (PoLP) by granting only the minimum access required for each workflow or job.

Permission scope

Each permission key accepts a single scope value. If defined more than one is defined, then the last entry takes precedence.

Configure permissions at two levels:

Workflow level: applies to all jobs in the workflow.
Job level: applies to a specific job and overrides the workflow-level value for that key.

When a permission key value is not supplied at the job level, the specified or default workflow-level value is applied.

Permission keys and values

The following table describes the available permission keys, allowed values, and what each controls:

Permission Key Values Description

Permission Key	Values	Description
`scm-token-own`	Values: `read`, `none` Default: `read`	Grants access to the user-level SCM token.
`scm-token-org`	`read`, `none` Default: none	Grants access to the organization-level SCM token.
`id-token`	`write`, `none` Default: `none`	Grants access to the OpenID Connect (OIDC) identity token.

scm-token-own

Values: read, none

Default: read

Grants access to the user-level SCM token.

scm-token-org

read, none

Default: none

Grants access to the organization-level SCM token.

id-token

write, none

Default: none

Grants access to the OpenID Connect (OIDC) identity token.

Best Practices

To ensure robust access control and security, follow these key recommendations:

Explicitly define permission levels rather than relying on defaults.
Limit the SCM access to the minimum access required, as defined by the Principle of Least Privilege (PoLP).
Use job-level permissions for finer-grained access control when needed.
Perform regular audits to remove excessive or unnecessary permissions.

Following these practices helps ensure workflows remain secure, compliant, and maintainable.

Usage example

The following example demonstrates how to configure explicit permission settings at the workflow level. These permissions either grant read or write access to tokens, or deny access entirely by setting the value to none.

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Secure workflow with custom permissions
on:
  push:
    branches:
      - '**'
permissions:
  scm-token-own: read          (1)
  scm-token-org: none          (2)
  id-token: write              (3)
jobs:
  example-job:
    steps:
      - name: Print token info
        uses: docker://alpine:3.18
        run: echo "Example job running with custom permissions."▼

1	Grants read-only access to the user-level SCM token. This is typically used for operations like cloning a repository or fetching source code.
2	Explicitly denies access to the organization-level SCM token, enhancing workflow security by restricting broader repository access.
3	Grants write access to the OIDC identity token, enabling generation of signed identity credentials used for authenticating to external services or APIs.