GitLab CI/CD

A GitLab CI/CD job on GitLab.com reads secrets under a machine you register for its project. The job authenticates with a token GitLab issues for it. You add the machine here, then give the job its token and point it at your Burrow. For a server or container you run a command on, see Command / Ed25519.

Add the machine#

1. Open Machines and use the + at the top right, then set the method to GitLab CI/CD and select Continue.

2. Name the machine, then enter the namespace (a group, with any subgroups, or a user), the project name, and the top-level CI file path such as .gitlab-ci.yml. Environment is optional; set it to pin the machine to one deployment environment.

3. Choose the audience the job's token names. It defaults to your Burrow's address.

4. Select Add machine.

The machine authenticates only a token whose project, CI file, and, when you set one, environment match what you entered. The CI file must be in the project itself. The machine appears on the Machines page with its project in place of a key fingerprint.

Point the job at your Burrow#

In .gitlab-ci.yml, give the job an ID token named RATEL_ID_TOKEN for your Burrow, install the CLI, select OIDC, and read secrets:

deploy:
  image: node:22
  id_tokens:
    RATEL_ID_TOKEN:
      aud: https://your-burrow
  script:
    - npm i -g @ratelkey/cli
    - ratel auth use oidc --burrow https://your-burrow --tls system
    - ratel secret get myapp/prod/DATABASE_URL

Connection#

How the job trusts your Burrow is set by --tls on ratel auth use oidc, the same choice you would make under Connection for a command machine.

If you chose an audience other than your Burrow's address, add --audience with it, and set the same value as the token's aud.

Once the machine exists, give it access and manage it from Machine grants.