Form rules
Rules you set up in a form, without Rego: Prodgator approvers, GitHub facts, attestations, required checks, change size, required reusable workflows, allowed actors and AI-assisted changes.
Availability
Form rules cover the common cases without writing Rego. For a ready-made policy built from these rules, see Policy templates.
Prodgator approvers
Requires a number of approvals given in Prodgator.
| Setting | Meaning |
|---|---|
| Users | Organization members who may approve. |
| Groups | Approver groups whose members may approve. |
| Required approvals | How many approvals are needed, from 1 to 20. |
| Allow self-approval | When off, an approval from the person who started the deployment does not count. Prodgator can only tell who started it when that person has linked their GitHub account in Prodgator. When on, a self-approval on a release counts only if the approval settings that apply (the gate's, the deployment environment's or your organization's) also turn self-approval on. |
A rejection from any eligible approver fails the rule.
When an approval does not count
Prodgator records every approval, but the rule counts only approvals that meet its settings. The deployment card says which approvals did not count and why, for example "Does not count: Nate Ferrell triggered this deployment, and this rule does not allow self-approval." An approval does not count when:
- the approver started the deployment (their linked GitHub account is the workflow run's actor) and self-approval is off in the rule or in the approval settings,
- the approver is not one of the rule's users and not in one of its groups,
- on a pull request, the approval was given on an earlier commit and the rule asks again after a new commit.
Approving more than once changes nothing: the rule reads each person's latest answer, and the card shows it once with a count.
Clicking Approve can still submit your required-reviewer review on GitHub (reviewer forwarding) when your approval does not count toward the policy. The two gates are separate: the GitHub review answers the environment's required reviewers, and the Prodgator protection rule waits for the policy.
If the deployment is stuck because everyone who could approve it started it, you can:
- ask another member of the approver group, or another listed user, to approve it,
- add a second person to the approver group, then have them approve,
- allow self-approval in the rule (a new policy version) and turn self-approval on in the approval settings, then click Re-evaluate,
- switch the policy to observe or remove its binding (both need the role and are written to the audit log), and switch it back afterwards.
A break-glass override does not help here: it only covers compliance policies.
GitHub facts
Checks facts about the deployment on GitHub.
| Setting | Meaning |
|---|---|
| Allowed branches | The deployment must come from one of these branches. Leave empty to allow any branch. |
| Required checks | These check runs must finish with success, neutral or skipped. The rule waits while they run and fails if one fails. |
| Required labels | The pull request behind the commit must carry all of these labels. |
| Actor must be linked | The person who started the deployment must have linked their GitHub account in Prodgator. |
If Prodgator cannot read the facts from GitHub, the rule returns and Prodgator tries again later.
Attestations
Requires attestations sent by the Prodgator report action for the deployment's commit, each with status . Attestations from any workflow run on that commit count, so a CI workflow can provide the evidence a separate deploy workflow is gated on.
| Setting | Meaning |
|---|---|
| Requirements | 1 to 20 rows. Each names a kind (test results, coverage, SBOM, scan, build provenance or custom) and, optionally, the attestation's name and a workflow file pattern such as or . |
| Only count trusted sources | On by default. Ignores attestations from fork pull requests, and runs (see untrusted sources). |
For each requirement, the newest matching attestation decides. satisfies it; , and do not. With no matching attestation yet, the rule is . A rerun that sends a passing attestation replaces an earlier failure.
The rule fails when any requirement has a newest attestation that does not pass, waits while one is missing, and returns when Prodgator cannot read attestations. A report from any run on the same commit re-evaluates every deployment waiting for approval on that commit at once (up to 50 per report, newest first; the rest are picked up by the scheduled re-checks).
Required checks
Requires GitHub check runs and commit statuses on the commit (the pull request's head, or the release's commit). Works for releases and pull requests.
| Setting | Meaning |
|---|---|
| Required checks | Check names that must finish with success, neutral or skipped. matches any characters, so covers and , and alone covers every check. |
| Ignored checks | Checks that Require every check to be green skips, for example . |
| Require every check to be green | Every check on the commit, other than the ignored ones, must finish with success, neutral or skipped. |
| If the pull request has no other checks | Pass (the default) or Keep waiting. See below. |
| Seconds to wait for checks to start | 0 to 1800, default 120. Only used with Pass. |
The rule fails when a required check fails, and waits while one is still running. If some checks ran on the commit but none matches a required name, the rule keeps waiting: that required check is missing.
Checks GitHub requires that have not started
On a pull request, Prodgator also reads the status checks that GitHub requires on the base branch: required status checks in repository and organization rulesets, and in classic branch protection. It leaves out Prodgator Policies itself. A required check that has not reported on the commit yet counts as a check that is coming, so the rule waits for it with the reason "waiting on required checks that have not started", followed by the check names. This covers a pull request from a fork whose workflows wait for a maintainer to approve them, and one whose workflows cannot run because of merge conflicts. GitHub lists those checks as "Expected" on the pull request.
- A required name, included, matches these checks by name, so waits for every required check, reported or not.
- Require every check to be green waits for them too, unless they match an ignored name.
- A workflow run on the commit that is queued, waiting, or waiting for approval also counts as a check that exists and has not finished.
Prodgator reads the base branch's rules with the GitHub App's Administration: Read and Metadata: Read permissions, and reuses what it read for up to 5 minutes per repository and branch. Workflow runs are read with Actions: Read. When a run is created or finishes, and when a check suite finishes, Prodgator evaluates the pull request again.
When no other checks run
Some commits get no checks at all, for example a change to files no workflow runs on. The only check on them is Prodgator Policies itself, the base branch requires no other check, and no workflow run is pending. With Pass, the rule waits for checks to start and then passes with the reason "no other checks ran on this commit". It waits for the number of seconds you set, counted from when Prodgator first saw the commit: the first evaluation of the pull request's head commit (or merge group commit), or the deployment's creation for a release. That gives CI time to register its checks. Until then the rule is pending with the reason "waiting for checks to start", and Prodgator evaluates the pull request or release again when the time is up, even if GitHub sends nothing else. If a check starts during that time, the rule works as usual.
If Prodgator cannot read the base branch's required checks (for example, the installation has not accepted Administration: Read), it does not pass a pull request with nothing reported. The rule stays pending with the reason "could not read the branch's required checks", and Prodgator tries again a few times.
With Keep waiting, the rule waits until every required check reports, so a commit without checks stays pending until someone pushes a commit that runs them or overrides the gate.
Rules saved before this setting existed behave as Pass with 120 seconds. Policies saved before Prodgator read the base branch's required checks wait for them too, without being saved again.
Change size
Pull requests only. Limits how big a pull request may be, to keep changes small enough to review.
| Setting | Meaning |
|---|---|
| Most files changed | 1 to 10000. Leave empty for no file limit. |
| Most lines changed | 1 to 1000000, counting additions plus deletions. Leave empty for no line limit. Set at least one of the two limits. |
| Paths that do not count | Up to 50 globs on the file path. Matching files count toward neither limit. does not cross , does, and a pattern starting with also matches at the repository root. |
A new rule starts with 30 files, 800 lines and these paths: , , , , , , and .
The rule passes within the limits and fails above either one, with a reason that names the counts and the limits, for example "too large: 41 files changed, limit 30". It returns when Prodgator could not read the pull request's files from GitHub.
The totals come from GitHub and cover the whole pull request, but Prodgator lists at most 300 files. When a pull request has more, excluded paths are taken off only for the files in the list: files past it always count, so the rule can count too many but never too few. The reason says so when this happens.
Pull request details
Pull requests only. Checks where a pull request comes from and what state it is in.
| Setting | Meaning |
|---|---|
| Allowed head branches | Up to 50 globs on the branch the pull request comes from, such as or . does not cross , does. Leave empty to allow any branch. |
| Allow pull requests from forks | On by default. When off, a pull request whose head branch is in another repository fails. |
| Allow draft pull requests | When off, a draft waits with the reason "the pull request is a draft" and passes once it is marked ready for review. A new rule starts with this off. |
| Most files changed | 0 to 10000. Leave empty (or 0) for no limit. |
| Most lines changed | 0 to 1000000, counting additions plus deletions. Leave empty (or 0) for no limit. |
Turn on at least one check: allowed branches, a size limit, or forks or drafts off.
The rule fails for a branch that is not allowed, a fork when forks are off, or a size above a limit, naming each problem, for example "101 files changed, the limit is 100". With a size limit set, it returns when Prodgator could not read the pull request's files from GitHub. Unlike Change size, the counts cover every file; use Change size to leave out lock files and other generated paths.
Protected paths
Pull requests only, on the Business plan. Guards folders and files that need extra care, such as infrastructure or database migrations. The rule has 1 to 10 entries, each with:
| Setting | Meaning |
|---|---|
| Paths | 1 to 20 globs on the file path, such as or . does not cross , does, and a pattern starting with also matches at the repository root. |
| When these paths change | Block the pull request or Require approvals. |
| Approvals needed | With Require approvals: 1 to 20. |
| GitHub users, Approver groups | With Require approvals: who may approve. Leave both empty to count anyone's approval. |
A changed file counts for an entry when its path matches, and for a renamed file also when its old path matches, so moving a file out of a protected folder still counts.
An approval counts when it is a GitHub review that approves and is not stale, or a Prodgator approval given on the pull request's latest commit, from a listed user or a member of a listed group. The author's approval never counts, and someone who approves on GitHub and in Prodgator counts once.
The rule:
- fails when a Block entry matches, naming up to 10 of the paths, for example "changes to protected paths: infra/prod.tf",
- waits while a Require approvals entry has fewer approvals than it needs, for example "needs 2 approvals from octocat or the rule's approver groups for infra/**",
- passes when no protected path changed, or every matching entry has its approvals,
- returns when Prodgator could not read the pull request's files, and when more than 300 files changed: Prodgator lists at most 300 files, and a file past the list could be protected. Split the pull request or ask an admin to override the gate.
Code owners
Pull requests only, on the Business plan. Every changed file that has code owners needs an approval from one of its owners. Owners come from your file, which the Prodgator report action sends for the base branch. Prodgator uses the report for the base commit of the pull request, or else the latest report for the base branch.
| Setting | Meaning |
|---|---|
| Team owners | Map a GitHub team () to a Prodgator approver group. A Prodgator approval from a member of that group satisfies the team. Up to 50 mappings. |
| When the base branch has no ownership report | Wait for a report (the default), Fail the check or Pass the rule. |
Ownership follows GitHub's rules: the last matching line wins, a pattern starting with matches from the repository root, a pattern ending in matches everything in that folder, and a pattern without a matches at any depth. does not cross , does: matches but not . A line without owners leaves its files unowned.
A file is satisfied by an approving GitHub review that is not stale, or a Prodgator approval given on the pull request's latest commit, never the author's. A user owner () matches the reviewer's GitHub login, or the GitHub account linked to the Prodgator approver. A team owner () matches a Prodgator approval from a member of the mapped approver group.
The rule:
- waits while an owned file has no approval from its owners, naming up to 10 files and their owners, for example "needs approval from: @acme/platform (infra/main.tf), @ann (docs/a.md)",
- passes when every owned file has an approval, or when no changed file has owners,
- follows When the base branch has no ownership report when there is no report, with the reason "no ownership report for the base branch; add the ownership input to the Prodgator report action",
- returns when Prodgator could not read the pull request's files or the ownership report ("the ownership report could not be read right now"), and when more than 300 files changed.
GitHub's own code owner reviews still work through Require GitHub approval on a GitHub reviews rule, which reads GitHub's review decision. You can use both rules in one policy.
Security findings
Works for releases and pull requests. On the Business plan for pull requests, and it needs security findings in your plan. Limits how many security findings a change brings in and, if you like, how many the repository may have open.
| Setting | Meaning |
|---|---|
| New findings allowed | Per severity (critical, high, medium, low): how many findings the commit may introduce. Leave a box empty for no limit. A new rule starts at 0 critical and 0 high. |
| Open findings allowed | Per severity: how many open findings the repository may have, as the Security page counts them. Leave empty for no limit. |
| Wait for a security scan of the commit | When on, the rule waits until something reported on the commit. |
Set at least one limit, or turn on the scan setting.
What counts as new. Prodgator collects the findings reported for the commit: security reports and run reports uploaded for it and, for a pull request, GitHub's open code scanning alerts on the pull request's merge commit, the vulnerable packages the pull request adds (GitHub dependency review) and secret scanning alerts first found in one of its commits. The same finding reported twice counts once. A finding is new when it is not open on the baseline:
- When the pull request targets the repository's tracked branch (the branch the Security page follows): the repository's open findings from every source.
- When a pull request targets another branch: the open findings uploaded for that branch.
- For a release: the repository's open findings from every source, without the findings first seen in this commit's own reports. A release commit on the tracked branch opens findings on the Security page as soon as its reports are processed, so those findings still count as new for the release.
The rule:
- fails when a severity is over its limit, for example "introduces 1 critical and 2 high findings (limit 0 critical, 0 high)",
- waits with "no security scan reported for this commit yet" when the scan setting is on and nothing reported,
- returns when a limit is set and a source it needs could not be read, for example "code scanning alerts could not be read; try Re-evaluate", and when security findings are not part of your plan.
A GitHub source that is not set up for the repository (no code scanning, or no dependency graph) is skipped, not counted as an error. When GitHub refuses a read because of a rate limit, the source counts as not read and a rule with a limit returns for that evaluation. Re-evaluate to read it again. Security, GitHub's sources included, is read only for policies with this rule, custom rules or Rego.
Required reusable workflow
Requires that the GitHub Actions runs behind a change called one or more reusable workflows, for example your platform team's build or scan workflow. Works for releases and pull requests:
- A release reads the calls of the deployment's workflow run.
- A pull request reads the calls of every workflow run on its head commit (or merge group commit), together.
| Setting | Meaning |
|---|---|
| Reusable workflows | 1 to 20 patterns on the called workflow's path, written . matches within one folder, across folders, and case does not matter. A call inside the same repository () is matched with the repository's own name in front. |
| Which workflows | Every listed workflow must be called (the default) or One of the listed workflows is enough. |
| Allowed refs | Any ref, Tags only ( and other tags), Listed branches only, or Pinned commit SHAs only. |
| Branches | With Listed branches only: 1 to 20 branch names or globs, such as or . Prodgator cannot read branch protection in the called workflow's repository, so list the branches you protect there. |
| Allowed commit SHAs | With Pinned commit SHAs only: 1 to 50 full commit SHAs. The call must resolve to one of them, whether it names the SHA or a tag or branch that points to it. |
| Require an attestation from the workflow | Off by default. When on, only a trusted attestation sent by the Prodgator report action from a job inside the reusable workflow counts. Prodgator matches the job's and from its GitHub OIDC token. The run's list of calls alone is not enough. |
The rule:
- passes once the listed workflows were called at an allowed ref, all of them or one of them depending on Which workflows,
- waits with the reason "waiting for workflow runs to report" until a run has reported its calls,
- on a pull request, waits while a workflow run on the commit has not finished, naming the workflows it still waits for,
- with Require an attestation from the workflow, waits while a called workflow has not sent its attestation yet,
- fails once the runs finished without the calls ("not called: ...") or called them at a ref the rule does not allow,
- returns when Prodgator could not read the workflow runs (or the attestations, when it needs them), and for releases from GitLab, Bitbucket or Azure DevOps, which do not report reusable workflow calls.
Prodgator records the calls from GitHub's events. Runs recorded before the rule existed have no calls on record, so a release of such a run waits until its run sends another event, for example on a rerun.
Allowed actors
Limits who may start a release or author a pull request, by GitHub login, approver group or bot, and can require an approval from someone else. See Allowed actors.
AI-assisted changes
Asks more of an AI-assisted pull request or release: extra approvals, an approval from an approver group, or a label. Other changes pass. Business and Enterprise plans. See AI-assisted changes.
For any rule, choose whether it is blocking when you add it.