Reviewing commits

This feature is only available on the Enterprise plan.

This page walks reviewers through the review flow, shows how to enable/disable the feature, and how to review commits that have been placed in the "pending" state.

Overview

With review flow, when developers attempt to push changes to the BSR that fail a check, the push succeeds but the commits are marked as "pending" and are not available to downstream consumers until they're approved. The Buf CLI outputs a warning message to the committer, and sends an in-app notification and email to the owners notifying them that a commit needs to be reviewed.

Users can navigate to the inbox by clicking the Inbox icon next to their username in the top right corner of the BSR.

Commits that require approval are annotated as such in the repository's Commits tab, and all users see a prominent banner indicating that the repository requires attention.

This gives downstream consumers protection from unsafe schema changes, but allows for nuance in cases where those changes are acceptable.

Exceptions

Pushes to the BSR that fail the uniqueness check never enter review flow and always fail.

Enabling review flow

You must be a BSR administrator to enable review flow.

Warning

Once enabled, module owners and admins can approve commits that violate configured checks.

1. Go to the admin panel and select Checks in the Settings section of the menu.

2. Turn the Allow breaking changes to be approved by module administrators toggle on.

   

3. Click Update to save your settings.

Disabling review flow

Resolve pending commits

If your organization decides to disable this feature, we require that all pending commits be approved or rejected prior to disabling, preventing you from having "dangling" pending commits. To make this easy, we've added bulk approve and reject functionality to the BSR admin panel. From the admin panel, BSR admins can see all of the repositories with commits still in review. They can choose to bulk approve or reject remaining commits, or click into the repository itself to review the remaining commits more carefully.

Disable review flow

When no commits are left pending on the instance, the review flow can be disabled from the admin panel:

1. Go to the admin panel and select Checks in the Settings section of the menu.

2. In the Checks section, turn the Allow breaking changes to be approved by module administrators toggle off.

3. Click Update to save your settings.

After disabling the review flow, any already-rejected commits are still unavailable to downstream consumers.

Reviewing commits

You must be a repository owner or admin to review commits. As a reviewer, you work through any pending changes one by one, and approve or reject each commit. The result of the review is marked for posterity in the Commits tab.

Warning

Reviewing a commit is a one-way street—once reviewed, the commit stays approved or rejected forever.

1. Click the Review changes button in the notification, or go to the Commits tab for your module and click the Review changes button for the individual commit.

   The commit with the unsafe change and any other pending commits are shown in a queue on the left. The first commit's diff is shown in the center of the page, along with inline comments flagging each unsafe change.

   

   The diff compares the pending commit to the latest available commit on the default label. It's important to remember this after rejecting a commit or several—any future commits won't diff against previously rejected commits, but the latest in the repository.

2. For each pending commit, you have two choices:

   • Approve the commit, indicating that the change was deliberate and that any breakage with downstream clients is acceptable.
   • Reject the commit and continue preventing downstream consumers from accessing the change, which marks it as Rejected on the Commits tab. A follow-up commit is usually required from the committer after this, such as reverting the bad commit in Git or patching it another way.

If additional commits require review, you're taken through each one in the order they were pushed. You can exit the flow at any time and come back to it later without losing completed reviews. Once commits have been reviewed, the original committers receive emails notifying them that their commits have been evaluated, and the module's Commits tab reflects the review state of each commit.

Auto-approved commits

When a commit has been pushed with change that fails a check, additional commits may stack up behind it until the check failure is resolved. The BSR auto-approves commits where possible, according to the following rules:

• When you approve a pending commit, either:
  • It becomes available as the latest commit on the default label, marked as Approved on the Commits tab.
  • If there are other pending commits stacked up behind the pending commit, the BSR auto-approves them up to the next check failure, and the last of those commits becomes available as the latest commit on the default label.
• If you reject a commit and another commit is pushed that does not fail checks, any commits between the pending commit and the fixed commit are rejected. The fixed commit becomes available as the latest commit on the default label.