Set up a pull request gate

Start from a templateCopy Anchor Link

The quickest start is New from template on the Policies tab. It creates a pull request policy such as Require all status checks to pass, Require incremental changes or Do not merge label, and binds it to every repository on its default branch in the same dialog. See Policy templates.

Create a policy for pull requests, or add pull requests to a release policyCopy Anchor Link

Policies live on the Policies tab of the Gates page. When you create or edit a policy, set Used for to Pull requests, or to both Releases and Pull requests if the same rules should gate both.

Not every rule works for both subjects:

A policy can only use rules that work for every subject it targets. Set Used for to both and add a release-only rule, such as GitHub facts, and saving is refused with a message naming the rule and the subject to remove. A custom rule or a Rego policy works for both because it can read input.subject and branch on it.

Three example form rules:

• Required checks, set to build and test*: waits for those check runs (by exact name or a name pattern) to finish successfully, and fails if one of them fails. A pull request with no checks other than Prodgator Policies passes after a short wait by default; see Required checks.
• Labels, forbidding do-not-merge: fails the rule while the pull request carries that label.
• Attestations, requiring a coverage attestation from .github/workflows/ci.yml: waits for the Prodgator report action to send a passing coverage attestation for the head commit from that workflow file, the same as a release policy's attestation rule.

A custom rule or a Rego policy reads input.pullRequest, input.reviews, input.checks, input.files, input.attestations, input.security and, for a code owners rule, input.ownership. See Pull request input document.

Bind itCopy Anchor Link

Add a pull request binding: a repository pattern and a base branch pattern, using the same globs as release bindings (* does not cross /, ** does, matching ignores case). For example, acme/* and main binds every repository in acme whose pull requests target main. A GitLab project is matched by its full path, so acme/* covers acme/api but not acme/platform/api; use acme/** for a group with subgroups. A Bitbucket repository is matched as workspace/repository. A pattern matches the same path on every provider.

Binding a policy to pull requests starts a backfill: Prodgator lists the matching GitHub repositories' open pull requests and schedules an evaluation for each, so pull requests opened before the binding existed get the check too. You can also start it again from the Pull Requests page with Sync, which also reads open GitLab merge requests and Bitbucket pull requests. Binding a policy does not backfill those; without a Sync, an open one is picked up on its next event (a push or an approval).

Make the check requiredCopy Anchor Link

After the first Prodgator Policies check run appears on a pull request:

1. In the repository, go to Settings > Rules > Rulesets (or Settings > Branches for a classic branch protection rule).
2. Under Require status checks to pass, add Prodgator Policies.
3. Set its source to Prodgator GitHub Integration, so only Prodgator's own check run satisfies the requirement.

The Pull Requests page checks this for you. The Protected column shows, per pull request, whether the check is required on its base branch (Prodgator reads the default branch's rules, so a pull request into another branch shows as unknown). Expand a pull request to see its Merge protection on GitHub section: when the check is not required yet, How to require it offers a ready-made ruleset to download and import, and Add the ruleset with code has the same ruleset as a GitHub CLI command (Bash or PowerShell) or as Terraform (the integrations/github provider's github_repository_ruleset resource). The section also reports whether the requirement comes from an organization ruleset, a repository ruleset, or branch protection, and warns when the required check has no GitHub App pinned to it or is pinned to a different one.

To require the check across every repository in an organization at once instead of one ruleset per repository, use an organization ruleset (github_organization_ruleset) with a repository_name or repository_id condition alongside ref_name. Prodgator does not generate this variant: adapt the downloaded or Terraform ruleset by keeping its rules block unchanged and adding the repository condition, for example:

resource "github_organization_ruleset" "require_prodgator_policies" {
  name        = "Require Prodgator Policies"
  target      = "branch"
  enforcement = "active"

  conditions {
    ref_name {
      include = ["~DEFAULT_BRANCH"]
      exclude = []
    }
    repository_name {
      include = ["~ALL"]
      exclude = []
    }
  }

  rules {
    required_status_checks {
      required_check {
        context        = "Prodgator Policies"
        integration_id = 1234 # the Prodgator GitHub App's id
      }
      strict_required_status_checks_policy = false
    }
  }
}

To stop gating a repository, remove the binding first (the check turns neutral), then remove the required check.

On GitLabCopy Anchor Link

After the first Prodgator Policies status appears on a merge request's pipeline:

1. In the project, open Settings > Merge requests.
2. Under Merge checks, turn on Pipelines must succeed and save.

GitLab now refuses the merge while the merge request's head pipeline is not successful, which includes Prodgator's status being pending or failed. The setting applies to every target branch, so the Protected column shows the same answer for every merge request of the project; expand a merge request to see Merge protection with a link to the settings page when the setting is off.

Leave Skipped pipelines are considered successful off: a merge request whose only pipeline is Prodgator's status is never skipped, but a skipped CI pipeline would otherwise let a merge through before Prodgator posts.

To stop gating a project, remove the binding first (the status turns to a passing "no policy applies"), then turn the setting off if nothing else needs it.

On GitLab Ultimate: Prodgator as a status checkCopy Anchor Link

On GitLab Ultimate, Prodgator can be an external status check instead of a job in the merge request's pipeline. GitLab then asks Prodgator for an answer whenever a merge request changes, and no pipeline is created just to carry the result.

1. On the Pull Requests page, expand a merge request of the project and find Merge protection.
2. Choose Add Prodgator as a status check (admins only). Prodgator adds a check named Prodgator Policies to the project, covering the default branch when it is protected (every branch otherwise), and signs GitLab's requests with a secret it keeps for the connection.
3. In the project, open Settings > Merge requests and, under Merge checks, turn on Status checks must succeed.

From then on, Prodgator answers the status check for merge requests into the branches it covers and no longer posts the Prodgator Policies commit status on them: one signal per merge request. Merge requests into other branches keep the commit status. A commit status already posted on a merge request's current commit is still finished, so that pipeline does not stay running.

Prodgator answers only once the gate decides (passed or failed). While the gate waits, GitLab shows the check as pending; GitLab marks a pending check as failed after two minutes, and Prodgator's answer replaces that once the gate decides. Retry on a failed check asks Prodgator again.

Adding the check needs GitLab Ultimate and the Maintainer role for the GitLab account connected to Prodgator. If GitLab refuses, Merge protection says so, and the commit status with Pipelines must succeed keeps protecting merges. If someone deletes the check on GitLab, Prodgator goes back to the commit status on its next evaluation.

To stop using the status check, delete Prodgator Policies under Settings > Merge requests > Status checks. Disconnecting GitLab from Prodgator removes the secret, so GitLab's requests are refused; delete the check on GitLab too, or merges into the branches it covers wait on it.

On BitbucketCopy Anchor Link

After the first Prodgator Policies build status appears on a pull request:

1. In the repository, open Repository settings > Branch restrictions and add a restriction for the destination branch (or edit the one that matches it).
2. Under Merge checks, set Minimum number of successful builds for the last commit to at least 1.
3. Turn on Prevent a merge with unresolved merge checks (Bitbucket Premium) and save.

Bitbucket now refuses the merge while any build on the pull request's last commit, Prodgator's included, is failed or in progress. On Standard, step 3 is not available and the check is a warning only. Expand a pull request to see Merge protection for its destination branch, with a link to the branch restrictions when the merge is not blocked.

To stop gating a repository, remove the binding first (the build status turns to a passing "no policy applies"), then change the branch restriction if nothing else needs it.

On Azure DevOpsCopy Anchor Link

After the first Prodgator Policies status appears on a pull request, make it required on the target branch. The quickest way is from Prodgator: expand the pull request, find Merge protection and choose Require Prodgator Policies on the branch. You sign in to Microsoft once and Prodgator adds the branch policy. By hand:

1. In Azure DevOps, open Project settings > Repositories and choose the repository.
2. Open Policies, then the branch policies of the target branch.
3. Under Status checks, choose Add status policy and enter the genre prodgator and the name policies.
4. Set the policy to Required and save.

Azure Repos now blocks a merge into that branch until the status succeeds. The status is "not applicable" for a pull request no policy gates, which does not block it. Expand a pull request to see Merge protection for its target branch.

To stop gating a repository, remove the binding first (the status turns to "not applicable"), then remove the status policy if nothing else needs it.