When the check runs

When the check updatesCopy Anchor Link

Prodgator schedules a new evaluation when:

• the pull request is opened, pushed to, labeled, edited, marked ready for review, or its base branch changes,
• a review is submitted, dismissed or edited,
• another check run or commit status on the same commit finishes,
• a run report attestation for the commit arrives (the Prodgator report action),
• someone clicks Re-run on the check on GitHub, or Re-evaluate on the check or the Pull Requests page,
• someone approves or rejects the pull request in Prodgator, or an admin creates or revokes an override.

Triggers arriving close together are combined: Prodgator waits 10 seconds after the first one before evaluating, and any trigger arriving during that wait or during the evaluation itself schedules the next one instead of starting a second one at once.

If your organization moves to a plan without pull request gates while pull request bindings still exist, Prodgator stops evaluating. Each new head commit (and merge group) gets one neutral Prodgator Policies check that says "Prodgator PR gates are not included in this organization's plan", and nothing more. GitHub counts a neutral check as passing for a required check, so pull requests are no longer held by their policies. Upgrade again to enforce them, or remove the bindings and the required check.

Each head commit gets at most 50 automatic evaluations. After that, only a person's action (Re-run, Re-evaluate, an approval, an override) evaluates it again, and the check says the limit was reached. Your plan also has an hourly limit on evaluations per organization (see Plans and features); an evaluation over that limit is retried a little later.

Merge queuesCopy Anchor Link

With a merge queue enabled (Business and Enterprise), the merge group gets its own Prodgator Policies check. It reads reviews, Prodgator approvals, labels, the author and changed files from the pull request, but reads checks and attestations for the merge group's own head commit, since that is the commit CI actually runs on.

On Team, the merge group check copies the pull request's latest result for its current head commit instead of evaluating again, and waits if that result has not passed, so a queue never merges past a failing gate.

This needs the App's Merge queues: Read permission and the Merge group event. Without them the queue waits forever for a check that never arrives.

Drafts and commentsCopy Anchor Link

A draft pull request is evaluated by default. An admin can turn on Skip drafts for the organization, or for one binding, so drafts get a neutral check ("run when it is ready for review") instead. Marking the pull request ready for review evaluates it.

Besides the check, Prodgator keeps one comment on the pull request with the policy results: the overall state, one row per policy (Pass, Fail or Waiting, with the reason of the first failing or waiting rule), and links to the pull request in Prodgator and to the check run (the pipeline on GitLab, the commit on Bitbucket). GitHub pull requests, GitLab merge requests and Bitbucket pull requests all get it. The comment starts with a hidden marker, <!-- prodgator:policies --> (on Bitbucket, which shows HTML as text, [//]: # (prodgator:policies)), so Prodgator finds it again and edits it in place instead of posting a new one. If someone deletes it, the next evaluation that has something to say posts a new one. It is edited only when its text changes.

Choose when to comment under Pull request settings on the Pull Requests page:

• Only when failing or waiting (the default): a comment is added once the pull request fails or waits on a rule. When the policies pass later, the same comment is edited to the passing summary rather than deleted.
• Always: every gated pull request gets the comment, passing ones too.
• Off: no comment is added or edited. An existing comment stays as it was.

A binding can override the organization with its own PR comment setting. When several bindings match one pull request, the one that comments most wins (Always, then Only when failing or waiting, then Off). Overrides, merge queue checks and skipped drafts never add or edit the comment.

The comment never changes the result. If it cannot be written, the check or status is still posted, the evaluation records the error, and the comment catches up on the next evaluation.

• GitHub: the comment needs the GitHub App permission Pull requests: Read and write. Until an installation accepts it, the check run still works and the comment is left out. Comment writes count toward the installation's GitHub budget (see Limits and GitHub API use); when the budget is spent for the hour, the comment catches up on the next evaluation.
• GitLab: the comment is a merge request note written with the connection's token (api scope), so it shows as posted by the person who connected the group.
• Bitbucket: the comment is a pull request comment written with the workspace connection's token, which needs Pull requests: Write. It shows as posted by the person who connected the workspace.
• Azure DevOps: the comment is a pull request thread written with the organization connection's token (vso.code_write), so it shows as posted by the person who connected the organization. Prodgator finds its thread again by a property it sets on it, edits the first comment in place, and sets the thread to active while the gate waits or fails and to resolved when it passes.

GitLab merge requestsCopy Anchor Link

A merge request is evaluated when:

• it is opened or reopened, pushed to, or edited (title, labels, target branch),
• someone approves or unapproves it,
• its pipeline starts or ends, or one of its jobs ends (the Required checks rule reads the pipeline's jobs and any other commit status),
• a run report attestation for the commit arrives,
• someone clicks Re-evaluate on the Pull Requests page, approves or rejects it in Prodgator.

The same 10-second wait, per-commit cap and hourly limit apply. After a downgrade, each new merge request head gets one passing status saying the plan does not include pull request gates.

Prodgator posts the status only when the result changes. GitLab's status API accepts no repeat of pending and no change to a status that already finished; when the result changes after a success or failed, GitLab records a new status under the same name, and the newest one counts. A pending status whose description changes (waiting on checks, then waiting on an approval) keeps its first description until the result changes; the Pull Requests page always shows the current one.

Merge requests get the same policy comment, as a note (see Drafts and comments). GitLab has no merge queue for Prodgator to join. Drafts follow the same Skip drafts settings; a skipped draft gets a passing status saying so.

Bitbucket pull requestsCopy Anchor Link

A Bitbucket pull request is evaluated when:

• it is created, pushed to or edited,
• someone approves it, removes an approval, requests changes or removes a change request,
• another build status on its head commit is created or updated (a Pipelines build, or any other tool's),
• a run report attestation or a security report for the commit arrives,
• someone clicks Re-evaluate on the Pull Requests page, approves or rejects it in Prodgator.

The same 10-second wait, per-commit cap and hourly limit apply. After a downgrade, each new pull request head gets one passing build status saying the plan does not include pull request gates.

Prodgator writes the build status in place, under one key per commit, whenever the result changes. Its own status updates never trigger an evaluation. Merging (or declining) a pull request is recorded; a merge while the status was failing or in progress is recorded as a bypass.

Bitbucket pull requests get the same policy comment (see Drafts and comments). There is no merge queue. Drafts follow the same Skip drafts settings; a skipped draft gets a passing build status saying so.

Azure DevOps pull requestsCopy Anchor Link

An Azure DevOps pull request is evaluated when:

• it is created or updated: a new commit is pushed, or a reviewer votes,
• an Azure Pipelines run on its head commit finishes (the Required checks rule reads the pull request's statuses),
• a run report attestation or a security report for the commit arrives,
• someone clicks Re-evaluate on the Pull Requests page, or approves or rejects it in Prodgator.

The same 10-second wait, per-commit cap and hourly limit apply. After a downgrade, each new pull request head gets one passing status saying the plan does not include pull request gates.

Prodgator writes the status in place on the pull request's latest iteration, under the genre prodgator and the name policies, whenever the result changes. Its own status never triggers an evaluation. Completing a pull request is recorded. Completing one while the status was failing or pending is recorded as a bypass.

Azure DevOps pull requests get the same policy comment (see Drafts and comments). There is no merge queue. Drafts follow the same Skip drafts settings; a skipped draft gets a status of "not applicable" saying so.

Fork pull requestsCopy Anchor Link

Attestations sent from a fork pull request's own workflow run are not trusted evidence (see untrusted sources), the same as for release policies. An attestations rule that only counts trusted attestations ignores them.

A fork pull request's check runs do not carry the pull request association GitHub normally attaches, so Prodgator instead re-evaluates a fork pull request when its check suite or commit statuses finish.

A GitLab merge request from a fork is read like any other; pullRequest.isFork is true and headRepository names the fork when Prodgator can read it.

A Bitbucket pull request from a fork is evaluated and shown the same way, but Prodgator does not post a build status on the fork's commit, so a branch restriction cannot count it.

An Azure DevOps pull request from a fork is evaluated like any other. Prodgator reads the fork's commit and its statuses from the fork's repository.