Review teams

Code reviewers are organized into PullApprove review teams.

Each team can set their own review conditions — for example, deciding to review PRs where certain files are modified, certain labels are applied, or a PR is being merged into a specific branch.

A team can also have its own approval requirements, written review instructions, and more.

Conditions

Use conditions to determine when the team will be assigned to a pull request. Like other expressions, these can leverage the vast majority of the GitHub API for the pull request.

When the conditions are met, the team is assigned to the pull request and starts their review.

Review settings

Reviewers

You can put any number of users into a review team. Note that, currently, PullApprove teams have no connection to GitHub teams.

Approvals required

Each team can decide how many approvals are required. For example, the "QA" team might require 2 approvals, while the "Design" team might only require 1.

Reviews to request

When a team is assigned to a pull request, PullApprove can automatically request their review in GitHub.

Note that if this number is less than the approvals required, then it will effectively send that many requests at a time until the required number of approvals is met. So, if you have 2 approvals required and 1 review to request, then PullApprove will request the first reviewer and wait to request the next until the first review is complete.

Contributor points

The author and co-author values are used to implicitly "approve" the PR if the author or git co-author is a member of the team.

This can be used for "self-approved" PRs, which is otherwise not possible with GitHub's approval system.

Review instructions

When a team is assigned to a PR, the reviewer instructions are sent to the PR as a comment (@mentioning the pending reviewers).

Review instructions can be used to remind people how the process works, links to internal docs, or even provide a literal review checklist.

Labels

When labels are enabled for the organization, a "PA: {team} pending" label will be applied to the PR while the team is pending review. When the team is done reviewing, the label will be removed.

FAQs

What about GitHub team review requests?

The PullApprove GitHub integration will only create review requests for individual users. It will never send a review request for an entire GitHub team.

While settings now exist to convert team requests into individual requests, we prefer to keep the GitHub integration simple and focused on individual users.

Workflow step condition or team condition?

Steps and teams can both have conditions, and they can be used for similar things. When used together (ex. your "In review" step), you might find yourself wondering where to put a condition.

Phase conditions should be used if the same rule applies to all teams, without exception. An example of this might be to only require review if the PR is being merged into the repo's default branch:

If the rule can't be applied to all teams, or if you want to apply different rules to different teams, then you should use a team condition instead.

The most common example of this is to assign a team to PRs based on the files that are modified:

In short, if a rule can obviously be applied to all pull requests for all teams, then use a phase condition. And if not, then use a team condition.