Use deployment variables for environment secrets such as production keys, repository variables for settings tied to one repository, and workspace variables only for values every repository truly shares. Bitbucket overrides in the order pipeline, deployment, repository, workspace. Mark credentials as secured so they are masked in logs.
The three scopes
| Scope | Where set | Typical use |
|---|---|---|
| Workspace | Workspace settings, Pipelines | Shared credentials used across repositories |
| Repository | Repository settings, Pipelines | Repository specific configuration |
| Deployment | Repository settings, Deployments | Different credentials per environment |
Workspace variables need workspace administrator access. Repository variables are available to users with write access in the sense that builds can use them, and managing them needs repository admin. The page does not say who manages deployment variables, so check your own permissions.
Precedence
The documented order is Pipeline over Deployment over Repository over Workspace. A deployment variable overrides a repository or workspace value of the same name. That is useful, but it also means a repository variable with the same name as a workspace one silently changes behavior.
What secured means
Secured variables are hidden in build logs, and matching values are masked automatically, including URL-encoded forms. They cannot be edited, only replaced or deleted. Masking works on exact matches, so a secret that a script transforms, for example by encoding it twice, may still show in a log. Bitbucket also says never to put credentials in bitbucket-pipelines.yml, to rotate them periodically and after people leave, and to consider a secret manager that gives the build secrets at run time.
Choosing a scope
- Does one environment need this value? Use a deployment variable, and do not give production keys to test.
- Does only one repository need it? Use a repository variable.
- Do many repositories need the same value, and is it low risk? Workspace is fine.
- Is it a long-lived cloud key? Try to replace it with OIDC. See Bitbucket OIDC for AWS.
- Is it a credential at all? Mark it secured.
A workspace secret is readable by every build in every repository in that workspace, so it widens blast radius. Keep production secrets out of it.
Limits worth knowing
Names use letters, digits and underscores, are case-sensitive and cannot start with a digit. Values can reach 120,000 characters. Avoid naming a variable PATH. Shared pipeline variables allow 50 per pipeline and 100KB in total. Secured and runtime custom variables are not supported in YAML templating.
Try it yourself
Click through it at your own pace, or open it full screen. Look at where a check can stop a risky change before it reaches a deploy step.
Safeguard's policies and gates can add checks on changes before merge, and a free scan is at https://gold.safeguard.sh/scan.
Quick check
Can write access users read a secured value?
Bitbucket says secured values are masked in logs, and write access lets a user run builds that use them. Treat write access as access to the secret.
Where should production credentials live?
In deployment variables for that environment, or better, replaced by short-lived tokens.
Sources
- Atlassian: Variables and secrets, fetched 19 October 2026.
Last reviewed: 19 October 2026.
