How do I automatically upload Cerbos policies to Cerbos Hub from GitHub Actions?

To automatically upload Cerbos policies to Cerbos Hub from GitHub Actions: You upload Cerbos policies from GitHub Actions by adding a workflow file at .github/workflows/upload-policies.yml that runs on pushes to your main branch. The simplest current option is the cerbos-store-action, which handles the upload in a single declarative step. You can also call cerbosctl directly through Docker if you want tighter control over when policies are pushed.

What credentials does GitHub Actions need to push policies to a Cerbos Hub store?

GitHub Actions needs three values to push to a Cerbos Hub store. The store ID, a CERBOS_HUB_CLIENT_ID and a CERBOS_HUB_CLIENT_SECRET. Generate the client credentials in the Client credentials section of your store in Cerbos Hub and select Read and Write, otherwise the upload will fail. Store both under Settings, then Secrets and variables, then Actions.

Do I need a CI pipeline to sync policies with Cerbos Hub if I use GitHub?

No, you don't need a CI pipeline to sync policies with Cerbos Hub if you use GitHub. A CI pipeline is not required to sync policies with Cerbos Hub if you use GitHub. Cerbos Hub has a native GitHub connector that connects a repository directly to a policy store. Use a GitHub Actions workflow instead when you want control over exactly which commits trigger an upload, or when policy uploads need to happen alongside other build steps.

Should Cerbos policy tests run before uploading to Cerbos Hub?

Yes, Cerbos policy tests should run before the upload step. Cerbos test suites live alongside your policies and are discovered automatically by the cerbos compile command, so a failing test can block the workflow before a broken policy reaches your decision points. Cerbos Hub also runs compile and tests on its own build pipeline and blocks distribution when a test fails.

Where do I check whether a Cerbos policy upload from GitHub Actions succeeded?

Check the Actions tab in your GitHub repository. A run named "Upload Cerbos Policies" appears there, and a green checkmark next to the upload step means the policies reached your Cerbos Hub store. If the step fails, the most common causes are client credentials created without Read and Write permission, or an incorrect store ID.

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.

Note: If you are on GitHub, the cerbos-store-action wraps all of this into a single step and is the quickest route. Cerbos Hub can also connect a repository to a store directly, with no pipeline involved. The workflow below is what you want when you need control over exactly which commits trigger an upload.

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.
Nothing needs installing on the runner. The upload runs the cerbosctl CLI inside a container.

Step 1: Create the Workflow File

In your repository, create a new directory named .github/workflows.
Inside .github/workflows, create a new file named upload-policies.yml.
Copy and paste the following code into the upload-policies.yml file.
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

In your GitHub repository, go to the Settings tab.
In the left sidebar, navigate to Secrets and variables > Actions.
Click the New repository secret button.
For the Name, enter CERBOS_HUB_CLIENT_ID.
In the Secret box, paste your client ID value. Click Add secret.
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

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

Step 4: Verify the Run

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

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, Buildkite and Azure DevOps.