Skip to main content

GitOps overview

Learn how Permit.io GitOps writes the policy code that Permit generates to a Git repository you own, so you can review, test, and extend that policy with Git workflows. This page is for developers and platform teams who decide whether to manage their Permit policy as code.

What GitOps does in Permit​

The Permit dashboard and API are low-code tools. When you change a policy in the Policy Editor, Permit generates Open Policy Agent (OPA) Rego code for that policy. For an example of the generated code, see the permitio/opal-example-policy-repo repository.

With GitOps turned on, Permit writes that generated code to a Git repository that you own before the code reaches your policy decision point (PDP):

  1. You connect a repository to a Permit project with an SSH deploy key.
  2. Permit creates one branch per environment, named permit/generated/<env_id> by default.
  3. When you change the policy of an environment, Permit saves the generated code to that environment's branch.
  4. Permit syncs the branch to the PDPs of that environment.
  5. When you push your own commits to an environment branch, Permit detects the change and sends the updated policy to the PDPs of that environment.

Because you own the repository, you can add the controls of a software project to your policy: pull request reviews, tests, benchmarks, and a CI process that promotes changes between the branches of your environments.

Why manage policy as code​

Policy as code means your authorization policy is stored as versioned code, with the same tools and processes you use for application code:

  • Change history: every policy change is a Git commit, so you can see who changed what and roll a change back.
  • Review: policy changes go through the same pull request review as code changes.
  • Consistency: the same policy code runs in every environment that syncs from the repository, so environments don't drift apart.

Policy as code doesn't require you to write the policy by hand. Permit generates the Rego code from what you configure in the dashboard. Team members without Rego experience, such as product managers or support, can change the policy in the Policy Editor, and the change still lands in Git.

Extend the generated policy with custom Rego​

The repository can hold Rego code that you write next to the code Permit generates. Put your code in the custom folder of the repository. Your custom Rego can import and reference the generated packages, for example to add a deny rule that the Policy Editor can't express. See Write custom policies with GitOps.

The policy repository doesn't have to be your application's main code repository. You can use a dedicated repository for policy.

Cloud PDP doesn't run custom Rego

The Cloud PDP doesn't support custom policy as code (custom Rego through GitOps). To run custom Rego, deploy an Edge PDP. See Cloud PDP capabilities.

Set up GitOps​

To connect a repository, follow Connect a GitHub repository to Permit. The same steps apply to other Git providers that support SSH deploy keys.

To connect a repository from a terminal, use the permit gitops create github command of the Permit CLI.

For which plans include Git policy sync, see the Permit pricing page.

Next steps​

Contents

Edit this page

Need help?