---
title: "Automating Cerbos Policy deployments with BitBucket Pipelines"
description: "This guide shows you how to set up a BitBucket Pipeline to upload your Cerbos policies to a Cerbos Hub store automatically"
author: "Alex Olivier"
date: "2026-07-08T10:33:00.000Z"
canonical: "https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-bitbucket-pipelines"
image: "https://stylish-appliance-1c1cc1c30d.media.strapiapp.com/Cerbos_Hub_2_0_Bitbucket_Pipelines_f7e192a4f8.png"
tags: ["documentation"]
source: "https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-bitbucket-pipelines"
---

# 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](https://docs.cerbos.dev/cerbos-hub/policy-stores.html) whenever you push changes to the `main` branch of your repository.

> **Note:** Cerbos Hub can also [connect a repository](https://docs.cerbos.dev/cerbos-hub/policy-stores-git-github.html) 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](https://docs.cerbos.dev/cerbos-hub/policy-stores-cli-binary.html) 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.

```yaml
# 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](https://docs.cerbos.dev/cerbos/latest/policies/compile.html#_testing), 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](https://www.cerbos.dev/blog/mapping-business-requirements-to-authorization-policy) covers that groundwork, and [GitOps makes the case](https://www.cerbos.dev/blog/why-using-gitops-for-authorization-and-access-control-is-a-good-idea) for keeping policies in version control to begin with.

PS. Here is the same setup for [GitLab Runners](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-gitlab-runners), [CircleCI](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-circleci), [GitHub Actions](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-github-actions), [Buildkite](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-buildkite) and [Azure DevOps](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-azure-devops-pipelines).

## Wrapping up

Go to [Cerbos Hub](https://hub.cerbos.cloud/) to create a policy store and connect this pipeline to it, or [book a free session](https://www.cerbos.dev/workshop) if you'd like to consult with our team.

## FAQ

### How do I automatically upload Cerbos policies to Cerbos Hub from Bitbucket Pipelines?

You upload Cerbos policies from Bitbucket Pipelines by adding a bitbucket-pipelines.yml file that runs a step on your main branch. The step runs the cerbosctl container with your Cerbos Hub store ID and client credentials, and replaces the policy files held in the store.

### What credentials does Bitbucket Pipelines need to push policies to a Cerbos Hub store?

Bitbucket Pipelines needs your Cerbos Hub store ID plus a client ID and client secret. Create them in the Client credentials section of your store in Cerbos Hub with the Read and Write option selected, then add CERBOS_HUB_CLIENT_ID and CERBOS_HUB_CLIENT_SECRET as secured repository variables so the values stay hidden in build logs.

### Does Bitbucket Pipelines need the Docker service enabled for Cerbos policy uploads? 

Yes. The upload step runs cerbosctl as a container, so the Docker service has to be available to that step in bitbucket-pipelines.yml. Leaving it out is a common cause of the Cerbos upload failing before it reaches your policy store.

### Should Cerbos policy tests run before uploading to Cerbos Hub from Bitbucket?

Yes, run the tests as an earlier step in the same pipeline. Cerbos test suites sit next to your policies and are found automatically by cerbos compile, so a failing test stops the pipeline before a broken policy reaches your decision points.

### Where do I check whether a Cerbos policy upload from Bitbucket Pipelines succeeded?

Open the Pipelines section of your Bitbucket repository and select the most recent run. Each step shows a pass or fail state along with its log output. If the upload failed, check that the client credentials were created with Read and Write permission and that the store ID in the pipeline file matches the one in Cerbos Hub.