Bitbucket Pipelines

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

Find the repository's UUID#

Bitbucket identifies the repository in its tokens by UUID. In the repository on Bitbucket, open Repository settings, then OpenID Connect under Pipelines. Copy the repository's UUID, and, to pin the machine to one deployment environment, that environment's UUID. They can be copied with or without their braces.

Add the machine#

1. Open Machines and use the + at the top right, then set the method to Bitbucket Pipelines and select Continue.

2. Name the machine, then enter the workspace, as in bitbucket.org/<workspace>/, and the repository's UUID. Deployment environment UUID is optional; set it to pin the machine to one deployment environment.

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

4. Select Add machine.

The machine authenticates only a token from that workspace whose repository, and, when you set one, deployment environment, match what you entered. A repository has one pipeline file, so any step in it can use the machine; pin an environment to narrow it. The machine appears on the Machines page with its workspace and repository UUID in place of a key fingerprint.

Point the step at your Burrow#

In bitbucket-pipelines.yml, turn on OIDC for the step with your Burrow as an audience, install the CLI, select OIDC, and read secrets:

pipelines:
  default:
    - step:
        image: node:22
        oidc:
          audiences:
            - 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

Bitbucket's pipeline editor marks audiences as an error ("Use either a boolean or a section") and won't commit it. Edit bitbucket-pipelines.yml in the repository's file editor under Source, or push it with git, instead: the pipeline accepts it.

Connection#

How the step 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 list the same value in the step's audiences.

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