Pull request gates

What pull request gates doCopy Anchor Link

Prodgator checks each pull request against the policies bound to its repository and base branch and reports one check run, Prodgator Policies, on the head commit. Make that check required in GitHub and it blocks the merge until the policies pass.

GitLab merge requests get the same gate, reported as a commit status on the merge request's pipeline, or on GitLab Ultimate as an external status check. See GitLab merge requests below. Bitbucket Cloud pull requests get it as a build status on the pull request's head commit. See Bitbucket pull requests below. Azure Repos pull requests get it as a pull request status. See Azure DevOps pull requests below.

Pull request gates need the Team plan or higher. Attestations, security, custom and Rego rules, approver groups, protected paths, code owners, overrides, repository policy files (.prodgator/policies/), merge queue re-evaluation and the playground need Business or Enterprise. See Plans and features.

A policy kept in a repository file can bind pull requests directly: add pull_request to its subjects and a base entry to its bindings, the same way a UI-managed policy is bound to a base branch (see Bindings and Keeping policies in a repository).

The results show on the Pull Requests page.

Before you startCopy Anchor Link

1. Confirm your plan includes pull request gates (Team or higher; see the feature matrix in Plans and features).
2. Install the Prodgator GitHub App on the repository. See Connect GitHub. The App needs Checks: Read and write and Merge queues: Read, and every installation must accept these permissions once GitHub asks. Until an installation accepts, no check run is created for its pull requests.
3. For GitLab, connect the group. See Connect GitLab and the section below.
4. For Bitbucket, connect the workspace. See Connect Bitbucket and the section below.
5. For Azure DevOps, connect the organization. See Connect Azure DevOps and the section below.

GitLab merge requestsCopy Anchor Link

A merge request in a connected GitLab group is evaluated like a pull request: the same policies, bound to the project's path (for example acme/platform/api; ** covers subgroups) and target branch, the same results on the Pull Requests page, where merge requests carry a GitLab tag, and the same Approve and Reject in Prodgator.

The result is a commit status named Prodgator Policies on the merge request's head pipeline (the pipeline for the merge request's latest commit, or for the merged result when the project uses merged results pipelines). It is pending while a rule waits, failed when a blocking rule fails, and success otherwise. GitLab has no neutral status, so an observe-only policy, a skipped draft and "no policy applies" all show as success, with a description saying why. A merge request with no pipeline of its own gets a pipeline that holds only this status.

GitLab shows the status as an external job in the pipeline, and the pipeline keeps running until the status is posted as success or failed. Prodgator reads the pipeline's jobs and the commit's other statuses as checks and leaves out its own, so a Checks rule decides once the real jobs finish, never waiting on the pipeline that holds its own status.

To make it block the merge, turn on Pipelines must succeed under the project's Settings > Merge requests > Merge checks. GitLab then refuses to merge while the head pipeline, Prodgator's status included, is not successful. The Protected column and the Merge protection section of each merge request show whether the setting is on, with a link to the project's settings when it is off. Protected branch rules do not require specific statuses on GitLab; Pipelines must succeed is the one setting that counts, and it applies to every target branch.

Leave Skipped pipelines are considered successful off in the same settings. With it on, a merge request whose pipeline is skipped can merge without the Prodgator Policies status.

What Prodgator needs on GitLab:

• The connection's token has the api scope (asked for when the group was connected), and the person who connected the group has at least Developer access to the project: that is what posting a commit status and the policy comment takes.
• The webhook sends Merge request events. Prodgator adds the trigger to webhooks of older connections itself; see Connect GitLab if it could not.

What differs from GitHub:

• The policy comment is a note on the merge request, written as the person who connected the group (see Drafts and comments). GitLab has no merge queue for Prodgator to join.
• Binding a policy does not backfill merge requests: a merge request appears when its next event arrives (opening it, pushing to it, or approving it). To bring older open merge requests in, an admin can click Sync on the Pull Requests page.
• Re-evaluate from the Pull Requests page; GitLab's own pipeline retry does not rerun Prodgator's status.
• Policies that need GitHub facts, such as GitHub reviews reading GitHub's review decision, read GitLab's approvals instead: see the input document.
• The Security findings rule counts security reports and run reports only, and the Code owners rule has no ownership report to read (ownership reports come only from GitHub runs).
• An admin override passes the merge request's status for its current head commit, as it passes the check on GitHub. Once that passing status is posted, the override cannot be revoked: GitLab keeps a finished status for the pipeline, so the merge request would stay mergeable whatever Prodgator recorded. Revoke is not offered then, and the next commit is evaluated again. On GitHub the check run is updated in place, so an override can be revoked at any time.

Status checks on GitLab UltimateCopy Anchor Link

On GitLab Ultimate, an admin can add Prodgator as an external status check from a merge request's Merge protection section: see Set up pull request gates. GitLab then asks Prodgator for an answer when a merge request changes, Prodgator answers passed or failed once the gate decides, and Status checks must succeed blocks the merge. For merge requests into the branches the check covers, Prodgator stops posting the commit status, so there is one signal and no extra pipeline. Without Ultimate, or when GitLab refuses, the commit status above stays the way Prodgator reports.

When Prodgator looks againCopy Anchor Link

A merge request is evaluated again when GitLab sends a merge request, pipeline or job event for it, when a person acts in Prodgator, and when a security report for its commit finishes processing. While a Checks rule waits on checks, Prodgator also looks again on its own, six times at growing intervals (1, 2, 4, 8, 10 and 10 minutes apart), so a commit status from another tool that finishes without a job event is still picked up.

Bitbucket pull requestsCopy Anchor Link

A pull request in a connected Bitbucket Cloud workspace is evaluated like a GitHub pull request: the same policies, bound to the repository's workspace/repository name and destination branch, the same results on the Pull Requests page, where Bitbucket pull requests carry a Bitbucket tag and open on Bitbucket, and the same Approve and Reject in Prodgator.

The result is a build status named Prodgator Policies (key prodgator-policies) on the pull request's head commit, linked to the pull request on the Pull Requests page. It is INPROGRESS while a rule waits, FAILED when a blocking rule fails, and SUCCESSFUL otherwise. Bitbucket has no neutral state, so an observe-only policy, a skipped draft and "no policy applies" all show as SUCCESSFUL, with a description saying why.

Prodgator reads the commit's other build statuses (Bitbucket Pipelines and any other tool that posts one) as checks and leaves out its own, so a Checks rule never waits on Prodgator's own in-progress status.

To make it block the merge, add a branch restriction for the destination branch under the repository's Repository settings > Branch restrictions:

1. Under Merge checks, set Minimum number of successful builds for the last commit to at least 1. Bitbucket then counts the commit's builds, and a failed or in-progress build, Prodgator's included, fails the check.
2. Turn on Prevent a merge with unresolved merge checks. This needs Bitbucket Premium. On Standard, merge checks are only warnings: Bitbucket shows the failing check, but anyone with write access can still merge.

The Protected column and the Merge protection section of each pull request show whether its destination branch requires successful builds and whether merge checks are enforced, with a link to the branch restrictions when they are not. Branch restrictions are per branch, so pull requests into different branches of one repository can show different answers.

What Prodgator needs on Bitbucket:

• The connection's OAuth client has Pull requests: Read, and the person who connected the workspace can write to the repository: that is what posting a build status takes. The policy comment takes Pull requests: Write. Reading branch restrictions takes Repositories: Admin; without it, Prodgator reads the pull request's merge checks instead (see Connect Bitbucket).
• The workspace webhook sends Pull request events. Prodgator adds them to webhooks of older connections itself.

What differs from GitHub:

• The policy comment is a pull request comment, written as the person who connected the workspace (see Drafts and comments). There is no merge queue.
• Binding a policy does not backfill pull requests: a pull request appears when its next event arrives (opening it, pushing to it, or approving it). To bring older open pull requests in, an admin can click Sync on the Pull Requests page.
• Re-evaluate from the Pull Requests page; rerunning a pipeline in Bitbucket reruns your builds, and the gate is evaluated again when they report.
• GitHub reviews rules read Bitbucket's approvals and change requests instead: see the input document. Bitbucket pull requests have no labels.
• The Security findings rule counts security reports and run reports only, and the Code owners rule has no ownership report to read (ownership reports come only from GitHub runs).
• A pull request from a fork is evaluated and shown, but Prodgator does not post its build status on the fork's commit.
• An admin override passes the build status for the pull request's current head commit, and can be revoked at any time: Bitbucket replaces a build status with the same key, so revoking turns it back to the policies' result.
• A pull request merged while the build status was failing or in progress is recorded as Bypassed, with the person who merged it, and the organization is notified.

Azure DevOps pull requestsCopy Anchor Link

A pull request in a connected Azure DevOps organization is evaluated like a GitHub pull request: the same policies, bound to the repository's organization/project/repository name and target branch, the same results on the Pull Requests page, where Azure DevOps pull requests carry an Azure DevOps tag and open on Azure Repos, and the same Approve and Reject in Prodgator.

The result is a pull request status with the genre prodgator and the name policies (shown as prodgator/policies) on the pull request's latest iteration, linked to the pull request on the Pull Requests page. It is pending while a rule waits, failed when a blocking rule fails and succeeded otherwise. Azure DevOps has a neutral state, so "no policy applies" and a skipped draft show as not applicable, which does not block a merge even when the status is required.

Prodgator reads the pull request's other statuses (Azure Pipelines builds and any other tool that posts one) as checks and leaves out its own, so a Checks rule never waits on Prodgator's own pending status.

To make it block the merge, require the status on the target branch. Open the pull request in Prodgator, find Merge protection and choose Require Prodgator Policies on the branch. You sign in to Microsoft once, and Prodgator creates a Status check branch policy for the branch with the genre prodgator and the name policies, set to Required. Prodgator keeps no access from that sign-in. It needs permission to edit policies on the repository: if Azure DevOps refuses, the panel shows the steps to do it 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.

The Protection column and the Merge protection section show whether the target branch requires the status.

What Prodgator needs on Azure DevOps:

• The connection's access includes vso.code_status, for the status, and vso.code_write, for the policy comment. The person who connected the organization must be allowed to contribute to pull requests in the repository. If Azure DevOps refuses the status, the pull request's latest evaluation says so, and connecting again with an account that has the permission fixes it.
• The service hooks send Pull request events. Prodgator creates them when you connect.

What differs from GitHub:

• The policy comment is a pull request thread tagged by Prodgator, written as the person who connected the organization (see Drafts and comments). Prodgator edits its first comment in place and sets the thread to active while the gate waits or fails, and resolved when it passes. There is no merge queue.
• Binding a policy does not backfill pull requests: a pull request appears when its next event arrives. To bring older open pull requests in, an admin can click Sync on the Pull Requests page.
• Re-evaluate from the Pull Requests page. A finished Azure Pipelines run on the pull request's head commit also evaluates it again.
• GitHub reviews rules read Azure DevOps reviewer votes: see the input document. Prodgator never votes on a pull request.
• The Security findings rule counts security reports and run reports only, and the Code owners rule is not available, because Azure Repos has no code owners file.
• A pull request from a fork is read from the fork's repository.
• An admin override passes the status for the pull request's current head commit and can be revoked at any time: Azure DevOps replaces a status with the same name, so revoking turns it back to the policies' result.
• A pull request completed while the status was failing or pending is recorded as Bypassed, with the person who completed it, and the organization is notified.

RelatedCopy Anchor Link