Cerbos Hub GitHub Integration

The Cerbos Hub GitHub integration allows you to manage your policies in a GitHub repository. This integration supports both public and private repositories, enabling you to store your policies securely and manage them using Git workflows.

Prerequisites

Before you can use the Cerbos Hub GitHub integration, you need to have the following:

  • A GitHub account.

  • A GitHub repository where you want to store your policies.

  • Permission to add a GitHub App to your repository.

Setting Up the GitHub Integration

To set up the GitHub integration, follow these steps:

  1. Go to the Cerbos Hub and log in with your Cerbos account.

  2. Inside a workspace, create a new policy store by clicking on "Policy Stores" in the sidebar.

  3. In the Import tab, select "GitHub" as the source for your policy store.

  4. Follow the prompts to authorize the Cerbos Hub to access your GitHub account.

  5. Select the repository you want to use for storing your policies.

  6. Configure the branch or tag for the integration to track, and optionally a directory where your policies will be stored. GitHub connection setup

  7. Click "Save" to complete the setup.

Syncing a subdirectory

If your policies are stored in a subdirectory of your repository, you can configure the store to sync only that path. This is useful when your authorization policies are part of a larger monorepo or when you want to organize policies into separate directories.

When configuring the GitHub connection, specify the path to the directory containing your policies in the directory field. Cerbos Hub will only sync files from that directory and its subdirectories. You can also sync hidden directories (those starting with a dot) if needed.

For example, if your repository structure looks like this:

my-repo/
├── src/
├── docs/
└── policies/
    └── cerbos/
        ├── resource_policies/
        └── derived_roles/

You would set the directory to policies/cerbos to sync only the Cerbos policy files.

Using the GitHub Integration

Once the GitHub integration is set up, you can monitor and manage your policies directly in the GitHub connection tab. The integration will automatically sync changes made to the policies in your GitHub repository.

GitHub connection status

To reconfigure the GitHub integration, you can click on the "Update configuration" button in the GitHub connection tab. This allows you to change the repository, branch, or directory settings.