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.

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.

Step 1: Create the CI/CD File

1. In the root directory of your project, create a file named .gitlab-ci.yml.
2. Copy and paste the following code into it.
3. 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

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

Step 3: Commit and Push

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

Step 4: Verify the Run

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