Issue a workspace token
Only an owner or admin of the workspace can issue or revoke a token, on the Tokens page of the web app or through the resource API while signed in.
Choose the scopes
Give the token only what its job needs:
| Job | Scopes |
|---|---|
| Terraform that manages lines, skills, integrations, hooks and harness profiles | configure |
| Terraform that also manages secrets | configure, secrets |
| Terraform that also manages runner pools and runner trusts | configure, runners |
| Setting up workspace token trusts once, then revoking | trusts plus every scope the trusts grant |
CI that only runs terraform plan | plan |
| A script that only reads | read |
Every token needs one of read, plan or configure. trusts lets a token
create trusts that mint tokens with any scope it holds, so give it only to a
token with a short expiry. Workspace tokens
lists what each scope allows.
On the Tokens page, the trusts scope is the checkbox Token trusts.
Issue the token
Open Settings from the workspace menu, then Tokens, and click Create a token.
Under Name, enter a name of lowercase words joined by dashes, such as
terraform. To record what uses the token, fill in What it is for.
Under What it may do, select Read, Plan or Configure, and tick Secrets, Runners or Token trusts for each further scope the token needs.
Expires after starts at 90 days. If the token needs another expiry, choose it there. For one the list lacks, use the resource API.
Click Create token. The page shows the token under a heading that names it, such as "Copy the terraform token now". Click Copy token and put it in your secret store now: Spotlight shows it this once and keeps only a hash. Then click I've copied it.
If the form says Token terraform already exists. Please choose another name.,
a token in the workspace already has that name.
The name, scopes and expiry are fixed once the token is issued. To change them, issue a new token and revoke the old one.
Revoke a token
On the Tokens page, open the token's actions menu (the three dots at the end of its row), click Revoke token, then click Revoke token again to confirm. The token stops working at once.
Related
- Workspace tokens: the fields, scopes and errors.
- Web app: what the Tokens page shows.
- Run Terraform from GitHub Actions without a stored token
- Ways in: pools, trusts and tokens