---
title: "Automating Cerbos Policy deployments with CircleCI"
description: "This guide will help you set up a CI/CD pipeline in CircleCI to upload your Cerbos policies to a Cerbos Hub store automatically."
author: "Alex Olivier"
date: "2026-07-09T10:34:00.000Z"
canonical: "https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-circleci"
image: "https://stylish-appliance-1c1cc1c30d.media.strapiapp.com/Automating_Cerbos_Policy_deployments_with_Circle_CI_e76bd9eeb0.png"
tags: ["documentation"]
source: "https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-circleci"
---

# Automating Cerbos Policy deployments with CircleCI

This guide will help you set up a CI/CD pipeline in CircleCI 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 Git 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 CircleCI account, linked to your GitHub or Bitbucket account.
* Your repository "set up" as a project in CircleCI.
* 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 Config File
1. In your repository, create a directory named `.circleci`.
2. Inside `.circleci`, create a file named `config.yml`.
3. Copy and paste the following code into it.
4. 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
# .circleci/config.yml
version: 2.1

jobs:
  upload-policies:
    docker:
      - image: cimg/base:2024.01
    steps:
      - checkout
      - setup_remote_docker:
          version: 20.10.24
      - run:
          name: Upload Policies
          command: |
            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 "$(pwd)":/app \
              ghcr.io/cerbos/cerbosctl:latest \
              hub store replace-files /app --message="Policy upload from CircleCI"

workflows:
  build-and-upload:
    jobs:
      - upload-policies:
          filters:
            branches:
              only: main
```

## Step 2: Add Your Secrets
1. Go to the CircleCI dashboard and select your project.
2. Click **Project Settings** in the upper right.
3. In the sidebar, click **Environment Variables**.
4. Click **Add Environment Variable**.
5. Enter `CERBOS_HUB_CLIENT_ID` as the *Name* and paste your client ID as the *Value*. Click **Add Environment Variable**.
6. Repeat for `CERBOS_HUB_CLIENT_SECRET`.

## Step 3: Commit and Push
1. Commit the `.circleci/config.yml` file.
2. Push your changes to the `main` branch.

## Step 4: Verify the Run
1. Go to your project's dashboard in CircleCI.
2. You will see a new workflow running. Click on it to see the status of the `upload-policies` job.

## 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), [GitHub Actions](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-github-actions), [Bitbucket Pipelines](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-bitbucket-pipelines), [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 CircleCI?

You upload Cerbos policies from CircleCI by adding an upload-policies job to .circleci/config.yml and filtering the workflow so it only runs on your main branch. The job checks out the repository, enables remote Docker, and runs the cerbosctl container to replace the files in your Cerbos Hub store.

### Why does the CircleCI config for Cerbos policy uploads need setup_remote_docker?

The CircleCI job needs setup_remote_docker because the upload runs the cerbosctl image as a container. CircleCI jobs that already run inside a Docker executor cannot start sibling containers without a remote Docker environment, so omitting this step is a common reason the Cerbos upload fails with a Docker daemon error.

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

CircleCI needs your Cerbos Hub store ID plus CERBOS_HUB_CLIENT_ID and CERBOS_HUB_CLIENT_SECRET. Generate the credentials in the Client credentials section of the store in Cerbos Hub with Read and Write selected, then add them as environment variables in your CircleCI project settings or a context shared across projects.

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

Yes, add a test job ahead of the upload job in your workflow. Cerbos test suites live alongside your policies and cerbos compile discovers them automatically, so a failing test stops the workflow before a broken policy reaches your decision points.

### Do I need CircleCI to sync policies with Cerbos Hub?

No. A Cerbos Hub policy store can be populated from a connected Git repository, a CI pipeline, the Hub SDKs, the cerbosctl CLI or a direct browser upload. Choose CircleCI when policy uploads need to sit alongside your existing build and test jobs, or when you want a specific branch filter controlling exactly which commits reach the store.