Description

This control ensures that all review comment conversations on a pull request targeting the default branch must be resolved before the pull request can be merged.

Rationale

Unresolved review comments may indicate open questions, requested changes, or identified defects and security issues. Requiring conversation resolution ensures that reviewer feedback is addressed or explicitly acknowledged before code is merged into the default branch.

Impact

  • Pull requests cannot be merged until all review conversations are resolved.

  • Authors and reviewers must explicitly resolve each conversation, which may add time to the merge process.

  • Ensures that reviewer feedback is not overlooked.

  • Improves code quality and supports change management requirements.

Default Value

  • Disabled by default. Repository administrators must explicitly enable conversation resolution in a ruleset or classic branch protection rule.

Remediation

Branch protection can be configured using rulesets, classic branch protection rules, or both. Complete the section that matches the repository's configuration. The control is met if either configuration enforces the requirement.

Rulesets

Test Plan

  1. Sign in to GitHub with administrative access to the repository.

  2. Navigate to the target repository.

  3. Select Settings.

  4. Under Code and automation, select Rules → Rulesets.

  5. Verify that an active branch ruleset targets the default branch, that Require a pull request before merging is enabled, and that Require conversation resolution before merging is enabled.

  6. Create a pull request against the default branch and add a review comment without resolving it.

  7. Attempt to merge the pull request. Expected result: the merge is blocked and GitHub indicates that all conversations must be resolved.

  8. Resolve the conversation and attempt to merge again. Expected result: the merge is allowed (subject to any other rules in place).

  9. If no active ruleset targets the default branch or the setting is not enabled, follow the Implementation Steps below to remediate the issue and repeat the test.

Implementation Steps

  1. Sign in to GitHub with administrative access to the repository.

  2. Navigate to the target repository.

  3. Select Settings.

  1. Under Code and automation, select Rules → Rulesets.

  1. Click New ruleset and select New branch ruleset, or edit an existing branch ruleset.

  1. Enter a name for the ruleset.

  2. Under Enforcement status, select Active.

  1. Under Target branches, click Add target and select Include default branch.

  1. In the Rules section, enable Require a pull request before merging.

  2. Under the additional settings for this rule, enable Require conversation resolution before merging.

  1. Click Create (or Save changes for an existing ruleset) to apply the ruleset.

Backout Plan

  1. Sign in to GitHub with administrative access to the repository.

  2. Navigate to the target repository.

  3. Select Settings.

  4. Under Code and automation, select Rules → Rulesets.

  5. Edit the applicable branch ruleset.

  6. Disable Require conversation resolution before merging.

  1. Click Save changes.

  2. Verify that pull requests with unresolved conversations can be merged according to the updated configuration.

Classic Branch Protection Rule

Test Plan

  1. Sign in to GitHub with administrative access to the repository.

  2. Navigate to the target repository.

  3. Select Settings.

  4. Under Code and automation, select Branches.

  5. Under Branch protection rules, verify that a rule matches the default branch (e.g., main).

  6. Click Edit next to the rule and verify that Require conversation resolution before merging is selected.

  7. Create a pull request against the default branch, add a review comment without resolving it, and attempt to merge. Expected result: the merge is blocked and GitHub indicates that all conversations must be resolved.

  8. If no matching rule exists or the setting is not selected, follow the Implementation Steps below to remediate the issue and repeat the test.

Implementation Steps

  1. Sign in to GitHub with administrative access to the repository.

  2. Navigate to the target repository.

  3. Select Settings.

  1. Under Code and automation, select Branches.

  2. Next to Branch protection rules, click Add classic branch protection rule, or click Edit next to an existing rule.

  1. In the Branch name pattern, enter the name of the default branch (e.g., main).

  2. Select Require conversation resolution before merging.

  1. Click Create (or Save changes for an existing rule) to apply the rule.

Backout Plan

  1. Sign in to GitHub with administrative access to the repository.

  2. Navigate to the target repository.

  3. Select Settings.

  4. Under Code and automation, select Branches.

  5. Click Edit next to the applicable branch protection rule.

  6. Clear Require conversation resolution before merging.

  1. Click Save changes.

  2. Verify that pull requests with unresolved conversations can be merged according to the updated configuration.

References