Test, import and store policies

PlaygroundCopy Anchor Link

The playground replays recent evaluations against a policy, so you can see how a change would have decided real deployments before you save it.

On a policy's page, open the Playground, load the policy's recent evaluations, pick the ones to replay and run them against your unsaved edits. Prodgator runs the edited policy on the input each evaluation used and shows the original decision next to the new one. It uses up to the 10 most recent evaluations.

Import and exportCopy Anchor Link

A Rego policy can move between Prodgator and a repository as a plain .rego file.

Export. On a Rego policy with one module (and at most one test module), click Export .rego. You get <name>.rego with a # METADATA block that holds the title, description, mode and bindings, plus <name>_test.rego when the policy has tests. Form and mixed policies stay in Prodgator and cannot be exported.

Import. On the Policies page, click Import .rego, choose the file and optionally its test file. Prodgator checks and compiles it, then shows what it will create: a new policy, or a new version of an existing policy you pick. Bindings in the file are created only when you tick the option to create them, only for entries that name a repository, and never twice. Files are limited to 128 KB each.

A file's # METADATA block looks like this:

# METADATA
# title: "Production gate"
# description: "Main branch and green checks"
# custom:
#   prodgator:
#     format: 1
#     mode: "enforce"
#     bindings:
#       - environment: "production"
#         repository: "acme/api"
package prodgator.policy

Exported files use prodgator: under custom:.

A policy that is also used for pull requests needs subjects: [release, pull_request] and a binding entry with base instead of environment:

# METADATA
# title: "Main branch"
# custom:
#   prodgator:
#     subjects: [release, pull_request]
#     mode: "enforce"
#     bindings:
#       - environment: "production"
#       - base: "main"
#         skipDrafts: true
package prodgator.policy

subjects defaults to [release] and is left out of exported files when that is all a policy needs. Each binding entry has either environment (needs release in subjects) or base (needs pull_request in subjects), never both. A base entry accepts the same *, ** and ? globs as environment, plus skipDrafts and comment (failing, always or off), matching the pull request binding options in the editor (see Bindings). Rego policies that target pull requests need the Business plan.

Keeping policies in a repositoryCopy Anchor Link

You can also keep policies in a repository instead of the editor. Put each policy in .prodgator/policies/<name>.rego, with an optional .prodgator/policies/<name>_test.rego, in the same format as an exported file. When a push to the default branch changes that folder, Prodgator reads the files, compiles them and saves each as a new version.

• Repository policies are read-only in Prodgator. Change them in the repository.
• A repository policy only ever binds its own repository. A repository key in its bindings is ignored.
• A base binding added this way starts the same backfill as binding a policy to pull requests in the editor: Prodgator lists the repository's open pull requests and schedules an evaluation for each.
• If a file fails to compile, Prodgator keeps the previous version, sends an organization notification naming the file and the first error, and records it in the audit log.
• Up to 50 policy files per repository are read, each up to 128 KB.
• The Prodgator GitHub App needs Contents: Read and the Push event for this.
• GitLab projects work the same way: a connected group's webhook sends Push events, and Prodgator reads the files with the connection's token. A GitLab project's policies bind its deployment environments by environment name; a workflow key is ignored. See Connect GitLab.
• Azure DevOps repositories work the same way: the organization's service hook sends Code pushed events for Azure Repos, and Prodgator reads the files with the connection's token. See Connect Azure DevOps.

Anyone who can push to the default branch can change these policies, including enforce policies that approve deployments. Protect the .prodgator/policies/ folder with branch protection and code owners the same way you protect your deployment workflows.