Pull request phases
In PullApprove, each pull request will flow through your review "phases" until it reaches the final "Approved" phase. The phases are evaluated in order, checking the conditions and requirements for each phase to see if it can move on to the next phase.
The default review phases are Pre-review → In review → Approved.
Requirements
The most important part of a phase is the requirements. These are rules that must be met for a pull request to move on to the next phase. Because phases are evaluated in order, you can think of the phases as a series of "gates" or "checks" that a pull request must pass to receive a successful status in GitHub.
Requirements are written as expressions that have direct access to the GitHub API. So, in addition to requiring your review teams to approve a pull request, you can also set up "pre-requisites" that need to met before a review takes place, or "post-requisites" that need to be met after review but before a pull request can be merged.
Examples of requirements:
- Team approval:
teams.all_approved
orteam["Team name"].approved
- Requiring PR labels:
len(pull.labels) > 0
- Requiring specific files to be changed:
"file.txt" in pull.files
- Preventing specific files from being changed:
"file.txt" not in pull.files
Conditions
By default, every pull request needs to pass the requirements of a phase. Phase conditions can be used to decide whether a pull request can skip a phase entirely.
An example of this is requiring review if a PR is being merged into the main
branch,
but allowing merges into other branches (i.e. develop
) without review.
If a PR doesn't meet the conditions then it skips straight to the next phase.
Examples of conditions:
- Specific repos:
pull.repo == "org/repo"
- Specific branches:
pull.base.ref == "main"
- Specific labels:
"review-required" in pull.labels
Notifications
To keep people in the loop about the status of a pull request, you can configure GitHub comments to be sent when a PR either enters or exits a specific phase.
You can use comments to provide concrete next steps for reviewers and contributors:
Notifications are rendered using templates.