How do I automatically upload Cerbos policies to Cerbos Hub from GitLab CI?

You upload Cerbos policies from GitLab CI by adding a job to your GitLab CI configuration that runs cerbosctl against your Cerbos Hub store when changes land on your main branch. The job runs the cerbosctl container, passes your store ID and client credentials as environment variables, and replaces the policy files in the store.

What credentials does GitLab CI need to push policies to a Cerbos Hub store?

GitLab CI needs your Cerbos Hub store ID plus a client ID and client secret. Create the credentials in the Client credentials section of your store in Cerbos Hub with the Read and Write option selected, then add CERBOS_HUB_CLIENT_ID and CERBOS_HUB_CLIENT_SECRET as masked CI/CD variables in your GitLab project settings so they do not appear in job logs.

Can I sync policies to Cerbos Hub from GitLab without a pipeline?

Cerbos Hub's native Git connector currently covers GitHub repositories, so for GitLab a CI job is the practical route. Cerbos Hub policy stores also accept uploads through the cerbosctl CLI, the Hub SDKs and direct browser upload, so a pipeline is one of several options rather than the only one.

Should Cerbos policy tests run before uploading to Cerbos Hub from GitLab?

Yes, run your Cerbos policy tests as a job stage before the upload. Cerbos test suites sit next to your policies and are picked up automatically by cerbos compile, so a failing test can stop the pipeline before a broken policy reaches your decision points.

Where do I check whether a Cerbos policy upload from GitLab CI succeeded?

Open the CI/CD section of your GitLab project and look at the most recent pipeline. The upload job shows a pass or fail status and the full job log. Failures usually come down to client credentials created without Read and Write permission, an incorrect store ID, or CI/CD variables that were added to the wrong environment scope.

Automating Cerbos Policy Deployments With GitLab Runners

This guide shows you how to set up a GitLab CI/CD pipeline to automatically upload your Cerbos policies to a Cerbos Hub store whenever you push changes to the main branch of your 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 GitLab account and a project.
Access to Shared Runners (enabled by default on GitLab.com).
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 CI/CD File

In the root directory of your project, create a file named .gitlab-ci.yml.
Copy and paste the following code into it.
Replace [STORE_ID] with the ID of your Cerbos Hub store. You can find this in the Cerbos Hub UI under the store settings.

# .gitlab-ci.yml
upload-policies:
  image: docker:24.0.5
  services:
    - docker:24.0.5-dind
  script:
    - >
      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 "$CI_PROJECT_DIR":/app \
      ghcr.io/cerbos/cerbosctl:latest \
      hub store replace-files /app --message="Policy upload from GitLab"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

Step 2: Add Your Secrets

In your GitLab project, go to Settings > CI/CD.
Find the Variables section and click Expand.
Click Add variable.
For Key, enter CERBOS_HUB_CLIENT_ID. For Value, paste your client ID. Check the Protect variable and Mask variable boxes. Click Add variable.
Repeat the process for CERBOS_HUB_CLIENT_SECRET.

Step 3: Commit and Push

Commit the .gitlab-ci.yml file.
Push your changes to the main branch.

Step 4: Verify the Run

In your GitLab project, go to CI/CD > Pipelines in the left sidebar.
You will see your new pipeline running. Click on its status to see the job logs.

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 GitHub Actions, CircleCI, Bitbucket Pipelines, Buildkite and Azure DevOps.