Deployments

A deployment is a specific configuration of policy stores (such as 'production' or 'staging') that can be connected to a set of PDPs. Each new change to the underlying store(s) results in a new policy build that’s automatically delivered to the policy decision points (PDPs) if the tests are successful.

Source agnostic inputs: Populate a policy store from any Git provider, CI system, API, CLI, or direct upload, so your existing workflows remain intact.
Multi-store composition: Reference multiple stores in a deployment to separate ownership, for example security team versus product team, or to blend static Git-managed policies with dynamic API-driven rules.
End-to-end automation: Building, testing, and distribution of policies is fully managed by Cerbos Hub, giving you a consistent CI/CD style pipeline for authorization without the need for extra infrastructure.
Strong versioning: Every deployment attempt is attached to a set of immutable policy store versions, making it easy to audit exactly which policies were in effect at any given point in time and to revert any changes if needed.

Deployment overview

Each deployment page provides several tabs to manage and monitor your policy pipeline:

Builds: View the history of deployed versions, showing which policy bundles have been active and when. Each build shows the contributing policy stores and their versions.
Policies: Browse the current policies included in this deployment and view their contents.
Decision points: See the PDPs currently connected to this deployment. Each PDP shows its ID, the build it’s running, active sessions, Cerbos version, when it was last seen, and a link to its audit logs.
Embedded PDP rules: Configure embedded policy decision points for this deployment. Each rule defines policy filtering criteria (resources, actions, scopes, roles, versions), authentication requirements, and IP allowlists. Multiple rules can serve different clients or environments from the same deployment.
Client credentials: Manage API credentials scoped to this deployment for PDP connections, audit log collection, and authenticated ePDP bundle access.
Settings: Configure deployment options including which policy stores contribute to builds.

Deployed versions

The Builds tab displays the history of policy bundles that have been deployed. Each row in the table shows:

Build reference: A unique identifier for the build. Click to view detailed information about the build including test results and bundle contents.
Active from: The timestamp when this build was activated and pushed to connected PDPs.
Active to: The timestamp when this build was replaced by a newer version, or a dash if it is the currently active build.
Included policies: The policy stores and specific versions that contributed to this build. This makes it easy to trace exactly which policies were in effect at any point in time.

Browsing policies

The Policies tab shows the policies included in the deployment’s current build. A Source / Effect matrix toggle at the top of the tab switches between two ways of viewing them.

Source view

The source view lists the policy files in the bundle and lets you open any file to read its contents exactly as it was compiled. Use the bundle selector to switch between builds when you need to inspect an earlier version.

Effect matrix view

The effect matrix presents a resource’s permissions as a grid instead of as policy source. You choose the resource, policy version, and scope to view, and roles and actions are laid out on the axes, with each cell showing the effect that applies to that role-and-action combination in the compiled bundle:

Allow: The action is permitted for the role.
Deny: The action is denied for the role.
Conditional: The effect depends on a condition that is evaluated at request time against the principal and resource attributes.

This gives you an at-a-glance view of a resource’s effective permissions without reading through every policy file, which is useful for reviewing changes and explaining access to others.

Cells also indicate where a wildcard rule widens a match. A rule written against * or a pattern such as foo:* can apply to more specific actions or roles, and the matrix flags the cells that are influenced by such a rule so the broader grant is visible rather than hidden. This is an indication of which rules match a cell, not a full partial evaluation of the policy.

Derived roles and the custom roles defined by role policies each appear as their own rows rather than being folded into the roles they build on. A role policy narrows access rather than granting it, allowing an action only when it is permitted by both the role policy and a matching resource policy rule.

To focus on part of a large matrix, filter by role or action, and select a cell to drill into the underlying rules — including any conditions — that produce its effect.

Limitations

The matrix highlights the rules that match each cell rather than fully evaluating the policy, so keep these limitations in mind when reading it:

Scope: Effects reflect the selected scope only. Because scoped policies can override the effects defined higher in the scope hierarchy, switch scopes to review each one in turn.
Derived roles: Derived role rules are shown only in their own cells. They are not reflected in the cells of the parent roles they extend.
Custom roles: Role policy rules are shown only in their own cells. They are not reflected in the other cells whose effects they restrict.

Build life cycle

Whenever Cerbos Hub detects a change in any policy store connected to a deployment, it launches a new policy build.

In progress: The policy build is queued and begins processing.
Compilation: Policies from all contributing stores are compiled together. If compilation fails, the error is surfaced so you can diagnose it quickly.
Test execution: After successful compilation, Cerbos Hub runs all policy tests found across the contributing stores. Failures are displayed with full logs for debugging.
Bundle generation: When compilation and tests pass, the bundle is generated and all PDPs assigned to this deployment receive a push notification to download and activate the new bundle immediately.

Build details

Click on any build reference to view detailed information about that specific build.

Build summary

The top of the page displays key metrics at a glance:

Status: Whether the build succeeded or failed
Build completed: When the build finished
Build time: How long the build took to complete
Test results: Total tests run, passed, skipped, and failed

Compile and test stages

Expandable sections show the results of each build stage:

Compile: Shows whether policy compilation succeeded. Expand to see any compilation errors or warnings.
Test: Shows whether all policy tests passed. Expand to see detailed test results, including any failures with full output for debugging.

Bundle file explorer

The file explorer displays the contents of the generated policy bundle. Browse the directory structure organized by contributing policy store, and click any file to view its contents. This lets you verify exactly which policies were included in the bundle and inspect their contents without leaving Cerbos Hub.

Use the file explorer to:

Confirm the correct policy versions were bundled
Debug unexpected authorization behavior by examining the active policies
Audit which policies contributed to a specific deployment

For details on creating policy stores and connecting PDPs to receive bundles, see the related guides:

Best practices

Use meaningful names: Name deployments after their purpose such as application, environment, or team, for example payments-service-production.
Automate testing: Include comprehensive test cases with each policy store to catch regressions before they reach production PDPs.
Validate in staging: Use staging deployments to verify policy changes in a pre-production environment before promoting to production.