A pipeline that deploys needs secrets, and storing them as CI/CD variables in GitLab means keeping a second copy you have to rotate. Instead, add the pipeline as a machine on your Burrow. For every job, GitLab signs a token that names the project and CI file, and your Burrow lets in only the pipeline you named.
What you need#
A Burrow your pipeline can reach over the internet, and a role that can add machines.
A project on GitLab.com with a CI file, such as
.gitlab-ci.yml.A project in your Burrow with the secrets the pipeline needs. This guide uses
api.
Add a GitLab CI/CD machine#
Open Machines in your Burrow and select the + at the top right of the table. Set the method to GitLab CI/CD and select Continue.
Name the project and CI file#
Give the machine a name you'll recognise, like deploy. Then enter where the pipeline lives:
Namespace: the group or user that owns the project, with any subgroups,
northwindhere.Project name: the project alone,
api.Top-level CI file path: the CI file in the project,
.gitlab-ci.yml.
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 job runs to sign in. Copy it; you'll paste it into the pipeline in step 5.
The command already carries how the job 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 .gitlab-ci.yml, give the job an ID token named RATEL_ID_TOKEN with your Burrow as its aud, install the CLI, sign in with the command you copied, and run your deploy with the project's secrets loaded:
deploy:
image: node:22
id_tokens:
RATEL_ID_TOKEN:
aud: 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 a commit. The job 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 job has no ID token. Add id_tokens to the job with a token named RATEL_ID_TOKEN, and set its aud to your Burrow's address.
"No machine matches this token"
The job doesn't match the machine. Check that the namespace, project name and CI file path are exactly what the job uses, that the CI file is in the project itself, that the token's aud is your Burrow's address, and, if you set an environment, that the job deploys to it.
The job 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: GitLab CI/CD in the documentation.
