---
title: "Automating Cerbos Policy deployments with GitHub Actions"
description: "This guide shows you how to set up a GitHub Actions workflow to upload your Cerbos policies to a Cerbos Hub store automatically."
author: "Alex Olivier"
date: "2026-07-05T10:38:00.000Z"
canonical: "https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-github-actions"
image: "https://stylish-appliance-1c1cc1c30d.media.strapiapp.com/Automating_Cerbos_Policy_deployments_with_Git_Hub_Actions_69a94e820b.png"
tags: ["documentation"]
source: "https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-github-actions"
---

# 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](https://docs.cerbos.dev/cerbos-hub/policy-stores.html) whenever you push changes to the `main` branch of your repository.

> **Note:** If you are on GitHub, the [cerbos-store-action](https://www.cerbos.dev/blog/automate-cerbos-policy-uploads-with-the-cerbos-store-action-git-hub-action) wraps all of this into a single step and is the quickest route. Cerbos Hub can also [connect a repository](https://docs.cerbos.dev/cerbos-hub/policy-stores-git-github.html) 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](https://docs.cerbos.dev/cerbos-hub/policy-stores-cli-binary.html) inside a container.

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

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

## 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](https://docs.cerbos.dev/cerbos/latest/policies/compile.html#_testing), 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](https://www.cerbos.dev/blog/mapping-business-requirements-to-authorization-policy) covers that groundwork, and [GitOps makes the case](https://www.cerbos.dev/blog/why-using-gitops-for-authorization-and-access-control-is-a-good-idea) for keeping policies in version control to begin with.

PS. Here is the same setup for [GitLab Runners](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-gitlab-runners), [CircleCI](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-circleci), [Bitbucket Pipelines](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-bitbucket-pipelines), [Buildkite](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-buildkite) and [Azure DevOps](https://www.cerbos.dev/blog/automating-cerbos-policy-deployments-with-azure-devops-pipelines).

## Wrapping up

Go to [Cerbos Hub](https://hub.cerbos.cloud/) to create a policy store and connect this pipeline to it, or [book a free session](https://www.cerbos.dev/workshop) if you'd like to consult with our team.

## FAQ

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