A pipeline that deploys needs secrets, and storing them as repository variables in Bitbucket means keeping a second copy you have to rotate. Instead, add the pipeline as a machine on your Burrow. For every step, Bitbucket signs a token that names the repository, and your Burrow lets in only the repository you named.
What you need#
A Burrow your pipeline can reach over the internet, and a role that can add machines.
A Bitbucket repository with a
bitbucket-pipelines.yml.A project in your Burrow with the secrets the pipeline needs. This guide uses
api.
Add a Bitbucket Pipelines machine#
Open Machines in your Burrow and select the + at the top right of the table. Set the method to Bitbucket Pipelines and select Continue.
Name the workspace and repository#
Give the machine a name you'll recognise, like deploy. Then enter which repository it's for:
Workspace: the workspace's ID, as in
bitbucket.org/northwind/, sonorthwindhere.Repository UUID: in the repository on Bitbucket, open Repository settings, then OpenID Connect under Pipelines, and copy the repository's UUID. It works with or without its braces.
Leave Audience on your Burrow's address and Connection on Encrypted + verified, then select Add machine.
Copy the sign-in command#
The machine is added, and the dialog shows the command your step runs to sign in. Copy it; you'll paste it into the pipeline in step 5.
The command already carries how the step checks your Burrow's identity. A Burrow with a public certificate uses --tls system, as here.
Give it a project#
A new machine can't read anything yet. Open Projects, open the menu on the project's row, and select Manage machines.
Tick the environments the machine may read. A deploy to production needs PROD and nothing else. Select Save.
Read secrets in the pipeline#
In bitbucket-pipelines.yml, turn on OIDC for the step with your Burrow among its audiences, install the CLI, sign in with the command you copied, and run your deploy with the project's secrets loaded:
pipelines:
branches:
main:
- step:
image: node:22
oidc:
audiences:
- https://burrow.northwind.dev
script:
- npm i -g @ratelkey/cli
- ratel auth use oidc --burrow https://burrow.northwind.dev --tls system
- ratel run --env api/prod -- ./deploy.shratel run loads every secret in api/prod into deploy.sh's environment in one read. To read a single value instead, use ratel secret get api/prod/DATABASE_URL.
Push to main. The step signs in as deploy, and every read shows on the machine's audit trail in your Burrow.
If it doesn't sign in#
"no OIDC provider detected"
The step has no token. Add oidc to the step with your Burrow's address among its audiences.
"No machine matches this token"
The step doesn't match the machine. Check that the workspace and the repository UUID are the ones on the repository's OpenID Connect page, that your Burrow's address is among the step's audiences, and, if you set a deployment environment, that the step deploys to it.
The step signs in but can't read the secret
The machine has no access to that project's environment. Open the project's Manage machines and tick the environment group the secret is in.
Every option in one place: Bitbucket Pipelines in the documentation.
