Automating Cerbos Policy deployments with Buildkite

This guide will help you set up a CI/CD pipeline in Buildkite 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 Buildkite account and a configured "Pipeline".
• Your own "agent" running on a machine that has Docker installed.
• 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: Configure Secrets on Your Agent Machine

Buildkite agents pull secrets from their environment. The simplest way is to define them directly on the agent machine.

1. Log into the server where your Buildkite agent is running.
2. Add your secrets to a system-wide environment file, like /etc/environment. Open it with a text editor (e.g., sudo nano /etc/environment) and add these lines:

CERBOS_HUB_CLIENT_ID="your-client-id-here"
CERBOS_HUB_CLIENT_SECRET="your-client-secret-here"

3. Save the file and restart your Buildkite agent service for the changes to take effect (e.g., sudo systemctl restart buildkite-agent).

Step 2: Create the Pipeline File

1. In your repository, create a directory named .buildkite.
2. Inside .buildkite, create a file named pipeline.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.

# .buildkite/pipeline.yml
steps:
  - 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 Buildkite"
    
    if: build.branch == 'main'
    label: "Upload Cerbos Policies"

Step 3: Commit and Push

1. Commit the .buildkite/pipeline.yml file.
2. Push your changes to the main branch.

Step 4: Verify the Run

1. Go to your pipeline in the Buildkite dashboard.
2. A new build will be triggered. Click on it to watch the "Upload Cerbos Policies" step execute on your agent.

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