Bitbucket Pipelines

Bootstrap an ephemeral machine inside your Bitbucket Pipelines run and pull SikkerKey secrets as environment variables at runtime.

SikkerKey integrates with Bitbucket Pipelines through a pipeline-time bootstrap. The dashboard generates a shell script and a bitbucket-pipelines.yml snippet that you commit to your repository. At runtime, the script registers an ephemeral machine bound to an enrollment token's policy, fetches the granted secrets, and exposes them as environment variables for subsequent pipeline steps.

Prerequisites

  • An enrollment token scoped to the projects and secrets your pipeline needs
  • Admin access to the target Bitbucket repository (required to add repository variables)
  • A pipeline image with curl and npm available (node:20, atlassian/default-image:4, etc.)

1. Add the enrollment token to Bitbucket

Copy the enrollment token plaintext. The plaintext is shown only once at creation; if you've lost it, revoke the token and create a new one.

In your Bitbucket repository:

Repository settings → Pipelines → Repository variables → Add variable

Set the name to SIKKERKEY_ENROLLMENT_TOKEN and paste the plaintext as the value. Mark the variable as Secured so Bitbucket masks it in pipeline logs and stores it encrypted at rest.

2. Generate the bootstrap script

In the SikkerKey dashboard, go to Integrations and click Build on the Bitbucket Pipelines row. Paste the same enrollment token plaintext into the modal. SikkerKey verifies it server-side and renders two files:

  • sikkerkey-init.sh: the bootstrap script. Commit it at the root of your repository.
  • bitbucket-pipelines.yml snippet: the pipeline configuration. Paste the relevant pieces into your existing bitbucket-pipelines.yml (or create a new one).

3. Use it in your pipeline

The full shape of a step that uses SikkerKey looks like this:

pipelines:
  default:
    - step:
        name: Deploy
        image: node:20
        script:
          - sh ./sikkerkey-init.sh
          - ./your-deploy-command.sh

SIKKERKEY_ENROLLMENT_TOKEN is injected automatically by Bitbucket from the repository variable you added above. After the bootstrap line runs, every command in the same step sees the granted secrets as environment variables.

What happens at runtime

  1. The script reads SIKKERKEY_ENROLLMENT_TOKEN from the step environment.
  2. It calls the SikkerKey enrollment endpoint, which generates a one-time Ed25519 keypair on the runner and registers an ephemeral machine bound to the token's policy.
  3. It installs the SikkerKey CLI via npm.
  4. It unlocks each project the token grants.
  5. It exports the granted secrets and prepends them to the step's environment for the remainder of the step.

Multiple steps

Each Bitbucket Pipelines step runs on a fresh container. If you have multiple steps that need secrets, add the bootstrap line to each. Every step produces its own ephemeral machine that disappears when the container is torn down.

Security model

  • Scoped token. The enrollment token can only register machines bound to its configured policy: projects, secrets, source CIDR, hostname pattern, machine TTL, and max uses. It cannot read secrets directly.
  • Ephemeral machine. Each pipeline step produces a unique machine identity, generated on the runner. The private key lives only in the runner's filesystem and is gone when the container is torn down.
  • Hash-only storage. SikkerKey stores only the SHA-256 hash of the enrollment token. The plaintext lives in Bitbucket's encrypted secured-variable store and is never sent back to you through SikkerKey.
  • Audit trail. Every enrollment, every secret read, and every machine action is recorded in your audit log, attributed to the parent token along with the runner's IP and timestamp.

Troubleshooting

./sikkerkey-init.sh: Permission denied. The committed script doesn't have the execute bit. The generated snippet invokes the script via sh ./sikkerkey-init.sh, which doesn't require it. If you've modified the snippet to drop the sh prefix, restore it.

Enrollment token not found (404). The plaintext you pasted into the dashboard modal doesn't match any token in your account. The plaintext is shown only once at creation. If you've lost it, revoke the token and create a new one.

Token has been revoked / expired / no remaining enrollments (410). The token can no longer enroll machines. Create a new token from Enrollment Tokens, regenerate the script, replace the SIKKERKEY_ENROLLMENT_TOKEN value in your repository variables, and re-run the pipeline.

Variable not visible to the script. Secured variables in Bitbucket are not propagated to pipelines triggered by external pull requests by default. Configure the trigger appropriately or invoke the pipeline from a branch in the same repository.