Bitbucket Pipelines - Manual Setup

For a faster setup experience, use the automated setup which handles everything from the dashboard.

Pipeline Configuration

definitions:
  steps:
    - step: &sikkerkey-secrets
        name: SikkerKey Secrets
        image: node:20
        script:
          - npm install -g sikkerkey 2>/dev/null
          - VAULT_DIR="$HOME/.sikkerkey/vaults/$SIKKERKEY_VAULT_ID"
          - mkdir -p "$VAULT_DIR"
          - chmod 700 "$HOME/.sikkerkey" "$HOME/.sikkerkey/vaults" "$VAULT_DIR"
          - echo "$SIKKERKEY_PRIVATE_KEY_B64" | base64 -d > "$VAULT_DIR/private.pem"
          - chmod 600 "$VAULT_DIR/private.pem"
          - printf '{"machineId":"%s","machineName":"bitbucket-ci","vaultId":"%s","apiUrl":"https://api.sikkerkey.com","privateKeyPath":"%s/private.pem"}' "$SIKKERKEY_MACHINE_ID" "$SIKKERKEY_VAULT_ID" "$VAULT_DIR" > "$VAULT_DIR/identity.json"
          - chmod 600 "$VAULT_DIR/identity.json"
          - sikkerkey connect $SIKKERKEY_VAULT_ID
          - sikkerkey unlock $SIKKERKEY_PROJECT_ID
          - sikkerkey export --project $SIKKERKEY_PROJECT_ID > sikkerkey.env
        artifacts:
          - sikkerkey.env

pipelines:
  default:
    - step: *sikkerkey-secrets
    - step:
        name: Build
        script:
          - source sikkerkey.env
          - echo "Secrets are available as environment variables"

The sikkerkey-secrets step installs the CLI, decodes the base64-encoded PEM key, configures the machine identity, fetches secrets, and exports them as an artifact. Downstream steps source the artifact to access secrets as environment variables.

Setup

1. Bootstrap a CI machine

From the dashboard, go to Machines and click + Validate. Select the CI/CD tab and run the command:

curl -sSL https://api.sikkerkey.com/v1/bootstrap/YOUR_TOKEN/ci | sh

This generates a keypair locally, registers the public key with SikkerKey, and prints the credentials.

2. Base64-encode the private key

Bitbucket pipeline variables cannot contain line breaks. Encode the PEM key:

cat private.pem | base64 -w 0

Copy the base64 output.

3. Add pipeline variables

In your Bitbucket repository, go to Repository settings > Pipelines > Repository variables and add:

All variables should be marked as Secured. Secured variables are encrypted at rest and masked in pipeline logs.

3. Approve and grant access

The machine appears as pending in the dashboard. Approve it, add it to your project, and grant it access to the secrets your pipeline needs.

Examples

Inject and run

pipelines:
  default:
    - step: *sikkerkey-secrets
    - step:
        name: Deploy
        script:
          - source sikkerkey.env
          - ./deploy.sh

Fetch individual secrets

pipelines:
  default:
    - step:
        name: Deploy
        image: node:20
        script:
          # ... CLI install + identity setup ...
          - export DB_PASSWORD=$(sikkerkey get sk_db_prod password)
          - export API_KEY=$(sikkerkey get sk_api_key)
          - ./deploy.sh

Security Notes

• Pipeline variables are stored as secured variables -- encrypted at rest and masked in logs
• The PEM key is base64-encoded to work within Bitbucket's variable format (no line breaks)
• The identity is created in the runner's home directory and discarded when the step ends
• Every secret read is authenticated with Ed25519 signatures and recorded in the SikkerKey audit log
• Each pipeline run uses the same machine identity, so all reads are logged with the same machine ID