Skip to content
baum

GitHub reviews and branch protection

When Sync to GitHub is on, baum copies a verdict to the pull request on GitHub as a pull request review. Approve becomes an APPROVE review and Request changes becomes a REQUEST_CHANGES review. The baum GitHub App posts every copy under its own name, and the review body names the person who gave the verdict. The only exception is the pull request author’s own verdict, which is posted as a COMMENT review. That review neither approves nor blocks the pull request.

Read this page before you rely on required reviews on a repository where the App is installed.

The App’s approvals can count toward required approvals

Section titled “The App’s approvals can count toward required approvals”

GitHub counts approvals from reviewers with write access toward required approvals. The baum GitHub App is created with Contents: write and Pull requests: write, and its approvals can count toward required approvals just as a person’s do. GitHub does not document this for GitHub Apps, so do not assume the App is excluded. This applies to classic branch protection rules and to rulesets that set Required approvals.

This lets one person supply more approvals than a rule intends:

  • Two approvals from one person. A reviewer approves on GitHub, then approves in baum. GitHub now sees two reviewers, the person and the App.
  • Approving your own push. Require approval of the most recent reviewable push stops the person who pushed last from approving that push. The App did not push, so an approval synced by that person still counts. This applies when the last pusher is not the pull request author, for example someone who pushed commits to another person’s pull request.
  • One reviewer for everyone. GitHub treats every synced verdict as coming from the App. However many people approve in baum, the App adds at most one approval, and GitHub goes by the App’s most recent standing review rather than by any one person’s verdict.

If a required-approvals rule must be met by people, configure the repository as described below.

Leave the App out of required-review counts

Section titled “Leave the App out of required-review counts”

GitHub has no setting that removes one reviewer from the Required approvals count. Keep that count for convenience if you like, but do not use it as the control that must come from people. Instead, require approval from people the App cannot be:

  • Code owners. Add a CODEOWNERS file that names users or teams for the paths you want to protect, for example * @your-org/reviewers for every file. Each team must be visible and have explicit write access to the repository. Then turn on Require review from Code Owners in the branch protection rule, or in the ruleset’s Require a pull request before merging rule. GitHub does not accept a GitHub App as a code owner, so an App approval never satisfies this requirement.
  • Required reviewers in a ruleset. In a ruleset’s Require a pull request before merging rule, add Required reviewers: choose one or more teams, the file patterns they cover (* for all files), and how many approvals each team must give. Only approvals from members of a team with write access count. A GitHub App cannot be a team member, so its approvals do not count here.

With either setting, a pull request still needs approval from a person on the named team, whatever the App posts. Because the App posts every synced verdict, a team member’s approval in baum does not meet the requirement. They must also approve on GitHub itself.

Also consider:

  • Dismiss stale pull request approvals when new commits are pushed. A new push then also clears the App’s earlier approval.
  • Restrict who can dismiss pull request reviews. Choose who may take back a review. If you set this, include the baum GitHub App. Otherwise, withdrawing or replacing a verdict in baum cannot take back its GitHub review. Also add the people who should clear App reviews by hand, as described in the next section.

A user who loses write access keeps their GitHub review

Section titled “A user who loses write access keeps their GitHub review”

In baum, withdrawing or replacing a verdict needs write access to the repository, just like giving one. Withdrawing a synced verdict dismisses its GitHub review. A person who loses write access can no longer do this, so any review the App posted for them stays on GitHub until someone dismisses it there. While it is the App’s most recent review, it counts as the App’s approval or request for changes.

When you remove someone’s write access, check their open pull requests for App reviews that name them. To dismiss one, you need write access to the repository. If Restrict who can dismiss pull request reviews is set, you must also be on its list:

  1. Open the pull request on GitHub.
  2. On the Conversation tab, open the list of reviews next to the review summary.
  3. Open the menu on the App’s review and choose Dismiss review.
  4. Enter a reason and confirm.

The verdict remains the person’s current verdict in baum. Dismissing only takes back the GitHub review.

Further reading

Section titled “Further reading”