Bitbucket Pipelines secrets from Crunu with step OIDC

What Crunu does in Bitbucket Pipelines

A step runs your command through crunu run. The crunu agent signs in with a service token, checks signatures, decrypts the variables in memory and starts the command with them. Nothing is written to disk.

crunu run --env web-app/staging -- npm test

The token gets only the environments you grant. With a CI binding (OIDC), it works only together with the step's OIDC token, for the repository, branch and deployment environment you set. crunu reads the step's token from BITBUCKET_STEP_OIDC_TOKEN by itself.

Set it up

1. In Crunu, open Service tokens and choose New service token. Grant the environments the step needs. The token is shown only once.
2. In Bitbucket, add secured repository variables: CRUNU_TOKEN and CRUNU_SERVER, plus CRUNU_INSTALL_URL, CRUNU_INSTALL_SHA256, CRUNU_VERSION and CRUNU_BINARY_SHA256 from the CI setup block on the token page. In the cloud, CRUNU_SERVER is https://app.crunu.com.
3. Optional: add a CI binding (OIDC) on the token page. Choose the Bitbucket provider, your workspace and the repository's repositoryUuid, and if needed branchName: main and the deploymentEnvironmentUuid of your production deployment.

Example pipeline

image: node:24

definitions:
  steps:
    - step: &test
        name: Tests with staging variables
        oidc:                 # only if the token has an OIDC rule
          audiences:
            - https://app.crunu.com   # your Crunu server as its own audience
        script:
          - curl -sSf "$CRUNU_INSTALL_URL" -o /tmp/crunu-install.sh
          - echo "$CRUNU_INSTALL_SHA256  /tmp/crunu-install.sh" | sha256sum -c -
          - sh /tmp/crunu-install.sh --version "$CRUNU_VERSION" --sha256 "$CRUNU_BINARY_SHA256" --user-install
          - crunu run --env web-app/staging -- npm test

pipelines:
  default:
    - step: *test

The step installs a pinned crunu, checks the installer's SHA-256 before running it, and runs the command in the step's own image with all its tools.

Why the audience matters

Set the audience to your Crunu server's address in the step's oidc: audiences:, as in the example. Bitbucket's default workspace audience also works, but every service in the workspace receives a token with it, so a dedicated audience is safer. A step can list up to 10 audiences. Bitbucket tokens carry no jti claim, so the Crunu server treats a second use of the same token as a replay and refuses it.

The crunu pipe

The product also includes a Bitbucket pipe that wraps these steps: it installs crunu, checks both checksums and runs your command with crunu run. Its image isn't published on a registry yet, so for now install crunu in the step as shown above. A step that uses the pipe references its image by address:

        script:
          - pipe: docker://<registry>/<name>:<tag>
            variables:
              CRUNU_TOKEN: $CRUNU_TOKEN
              CRUNU_SERVER: $CRUNU_SERVER
              CRUNU_ENV: 'web-app/staging'
              CRUNU_VERSION: $CRUNU_VERSION
              CRUNU_INSTALL_URL: $CRUNU_INSTALL_URL
              CRUNU_INSTALL_SHA256: $CRUNU_INSTALL_SHA256
              CRUNU_BINARY_SHA256: $CRUNU_BINARY_SHA256
              COMMAND: 'npm ci && npm test'

Pin the image to an immutable version tag or a digest. The command runs inside the pipe's container, which is based on Node.js 24 by default, not in the step's image. With an OIDC rule on the token, add oidc: with your server's audience to the step and OIDC: 'true' to the pipe's variables. Without that flag, the pipe passes the step's OIDC token neither to crunu nor to your command.

Keep the token out of reach

The command under crunu run gets only basic variables such as PATH and HOME, plus the environment's variables, and never crunu's own credentials. Bitbucket repository variables are still visible to every script line outside the pipe and to every step, so the real protection is a narrow grant: give a CI token the environment it builds, and keep production out of it.

Revoking

Open the token in Crunu and choose Revoke. Its next sign-in is refused, and a step that's already running finishes with what it received. If the token may have leaked, also rotate the keys of the environments it was given and reissue the values inside at their providers.

Related

• CI/CD in Crunu
• Bitbucket Pipelines in the docs
• Bind a token with OIDC
• Service tokens