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.

Note: Cerbos Hub can also connect a repository to a store directly if you are on GitHub. The pipeline below is what you want on any other CI service, or when you need control over exactly which commits trigger an upload.

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.
• • Nothing needs installing on the runner. The upload runs the cerbosctl CLI inside a container.

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.

Next steps

Add your policy tests to the same workflow so a broken policy never reaches the store. Cerbos test suites live alongside your policies and cerbos compile finds them automatically, so a failing test stops the run before the upload step.

If you are still working out what the policies themselves should say, mapping business requirements covers that groundwork, and GitOps makes the case for keeping policies in version control to begin with.

PS. Here is the same setup for GitLab Runners, CircleCI, GitHub Actions, Buildkite and Azure DevOps.

Wrapping up

Go to Cerbos Hub to create a policy store and connect this pipeline to it, or book a free session if you'd like to consult with our team.