Automating Cerbos Policy deployments with BitBucket Pipelines

Published by Alex Olivier on July 07, 2025
Automating Cerbos Policy deployments with BitBucket Pipelines

This guide shows you how to set up a Bitbucket Pipelines workflow to automatically upload your Cerbos policies to a Cerbos Hub store whenever you push changes to the main branch of your repository.

Prerequisites

  • A Bitbucket account and a repository.
  • Pipelines enabled for your repository (Repository settings > Pipelines > Settings).
  • The ID of your Cerbos Hub store, which you can find in the store section of the Cerbos Hub.
  • Your CERBOS_HUB_CLIENT_ID and CERBOS_HUB_CLIENT_SECRET values generated in the Client credentials section of the Cerbos Hub store. Make sure to select the Read & Write option when creating the credentials to allow uploading policies.

Step 1: Create the Pipeline File

  1. In the root directory of your repository, create a file named bitbucket-pipelines.yml.
  2. Copy and paste the following code into it.
  3. Replace [STORE_ID] with the ID of your Cerbos Hub store. You can find this in the Cerbos Hub UI under the store settings.
# bitbucket-pipelines.yml
pipelines:
  branches:
    main:
      - step:
          name: Upload Policies to Cerbos Hub
          services:
            - docker # Enable the Docker service
          script:
            - >
              docker run --rm \
              -e CERBOS_HUB_STORE_ID="[STORE_ID]" \
              -e CERBOS_HUB_CLIENT_ID=$CERBOS_HUB_CLIENT_ID \
              -e CERBOS_HUB_CLIENT_SECRET=$CERBOS_HUB_CLIENT_SECRET \
              -v "$BITBUCKET_CLONE_DIR":/app \
              ghcr.io/cerbos/cerbosctl:latest \
              hub store replace-files /app --message="Policy upload from Bitbucket"

Step 2: Add Your Secrets

  1. In your Bitbucket repository, go to Repository settings.
  2. In the left sidebar, under the "Pipelines" section, click Repository variables.
  3. Enter CERBOS_HUB_CLIENT_ID as the Name, paste your client ID in the Value box, and check the "Secured" checkbox. Click Add.
  4. Repeat the process for CERBOS_HUB_CLIENT_SECRET.

Step 3: Commit and Push

  1. Commit the bitbucket-pipelines.yml file.
  2. Push your changes to the main branch.

Step 4: Verify the Run

  1. In your Bitbucket repository, click Pipelines in the left sidebar.
  2. You will see a new pipeline run. Click on it to view the logs and status.

Book a free Policy Workshop to discuss your requirements and get your first policy written by the Cerbos team