Permissions
A permission defines which API and CLI actions an access token can take. Permissions are chosen the same way for both kinds of token:
- A service account holds a set of permissions, and its access tokens inherit them.
- A personal access token holds a set of permissions derived from the ones you hold.
Permission keys
Every permission is identified by a resource:action key, such as run:create or vault:unlock.
Only permissions a token can exercise through the API or the CLI are available.
Available permissions
| Resource | Key | What it allows |
|---|---|---|
| Runs | run:create | Trigger new runs. |
run:read | View run details, logs, and task outputs. | |
| Dispatches | dispatch:run | Trigger a dispatch. |
| Vaults | vault:create | Create new vaults. |
vault:write | ||
vault:create_secret | Add secrets to the vault. | |
vault:update_secret | Edit, rotate, and remove secrets in the vault. | |
vault:create_var | Add vars to the vault. | |
vault:update_var | Edit and remove vars in the vault. | |
vault:unlock | Unlock the vault to access secrets in a run. | |
vault:manage | Manage vault settings and delete the vault. | |
| Images | image:push | Push container images to a registry using |
| Captain | captain:run | Submit test results to Captain. |
Coarser permissions grant finer ones
A coarse permission automatically grants the finer permissions it implies. For example:
run:creategrantsrun:read. You can't trigger a run without being able to read it.vault:writegrantsvault:create_secret,vault:update_secret,vault:create_var, andvault:update_var.
vault:manage does not grant vault:create. A token can reconfigure and delete existing vaults without being able to add new ones.
Scoping vault permissions to specific vaults
Vault permissions can be applied to all vaults or only specific ones. A single token can have different permissions across different vaults.
You can only grant permissions you hold
A token is limited to the permissions you have yourself. Anything you don't hold isn't offered when you choose a token's permissions.
For a scoped vault permission, you can only target vaults you hold that permission on.