Automating Cerbos Policy deployments with GitHub Actions

Published by Alex Olivier on July 08, 2025
Automating Cerbos Policy deployments with GitHub Actions

This guide shows you how to set up a GitHub Actions workflow to automatically upload your Cerbos policies to a Cerbos Hub store whenever you push changes to the main branch of your repository.

Prerequisites

  • A GitHub account and a repository.
  • 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 Workflow File

  1. In your repository, create a new directory named .github/workflows.
  2. Inside .github/workflows, create a new file named upload-policies.yml.
  3. Copy and paste the following code into the upload-policies.yml file.
  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.
# .github/workflows/upload-policies.yml
name: Upload Cerbos Policies

on:
  push:
    branches:
      - main

jobs:
  upload-policies:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Upload Policies
        env:
          CERBOS_HUB_CLIENT_ID: ${{ secrets.CERBOS_HUB_CLIENT_ID }}
          CERBOS_HUB_CLIENT_SECRET: ${{ secrets.CERBOS_HUB_CLIENT_SECRET }}
        run: |
          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 GitHub Actions"

Step 2: Add Your Secrets

  1. In your GitHub repository, go to the Settings tab.
  2. In the left sidebar, navigate to Secrets and variables > Actions.
  3. Click the New repository secret button.
  4. For the Name, enter CERBOS_HUB_CLIENT_ID.
  5. In the Secret box, paste your client ID value. Click Add secret.
  6. Repeat the process: click New repository secret again. This time, use CERBOS_HUB_CLIENT_SECRET for the name and paste your client secret value.

Step 3: Commit and Push

  1. Commit the new .github/workflows/upload-policies.yml file to your repository.
  2. Push your changes to the main branch.

Step 4: Verify the Run

  1. Go to the Actions tab in your GitHub repository.
  2. You will see a new workflow run named "Upload Cerbos Policies". Click on it.
  3. You can see the job running. If it succeeds, you'll see a green checkmark next to the "Upload Policies" step.

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