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.

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

# .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, 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, GitHub Actions, Bitbucket Pipelines, 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.