Automating Cerbos Policy deployments with CircleCI

Published by Alex Olivier on July 07, 2025
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 whenever you push changes to the main branch of your Git repository.

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.

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.
# .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.

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