Blocking Comment

What Is a Blocking Comment?

A blocking comment is a code review comment that flags a critical issue in a pull request — one serious enough that the code should not be merged until the author addresses it. Unlike suggestions or nitpicks, a blocking comment signals a hard requirement: the reviewer has identified a bug, security vulnerability, data integrity risk, or architectural flaw that would cause real harm if it reached production.

Blocking comments are the backbone of effective code review. They represent the minimum bar of quality that a team enforces before code ships. When a reviewer leaves a blocking comment, they are saying: “I will not approve this PR until this is resolved.” On platforms like GitHub, a blocking comment is typically paired with a “Request Changes” review status, which formally prevents the pull request from being merged until the reviewer re-evaluates.

The distinction between blocking and non-blocking feedback is one of the most important skills a reviewer can develop. Conflating minor style preferences with genuine correctness issues slows teams down, breeds resentment, and dilutes the signal value of review comments. Conversely, failing to block on legitimate problems defeats the purpose of review entirely.

How It Works

Most code review platforms do not have a dedicated “blocking comment” feature at the comment level. Instead, reviewers rely on conventions and review-level actions to communicate severity. On GitHub, the flow typically looks like this:

1. The reviewer opens the “Files changed” tab and reads the diff.
2. They leave inline comments on specific lines where they see issues.
3. When submitting the review, they choose Request Changes instead of Approve or Comment.
4. Branch protection rules prevent the PR from merging until the reviewer submits a new review with Approve.

Many teams also adopt prefixes in their comments to make intent explicit:

# Blocking
blocking: This query is vulnerable to SQL injection.
Use parameterized queries instead of string interpolation.

# Non-blocking
nit: Consider renaming `data` to `userData` for clarity.
suggestion: You could extract this into a helper function.

AI code review tools like CodeRabbit have formalized this pattern. CodeRabbit classifies its findings by severity and can be configured to leave blocking versus non-blocking comments automatically, ensuring that critical security and correctness issues are always surfaced with the right urgency while style suggestions remain advisory.

In a typical GitHub Actions or CI workflow, blocking comments interact with branch protection rules:

# .github/branch-protection.yml (conceptual)
required_reviews: 1
dismiss_stale_reviews: true
require_code_owner_reviews: true

When a code owner requests changes, the PR cannot merge until the code owner explicitly approves again — even if other reviewers have approved.

Why It Matters

Blocking comments are the last line of defense before code reaches production. Their impact is measurable:

• Bug prevention. Google’s engineering practices documentation estimates that code review catches 60-90% of defects before they reach users. Blocking comments are the mechanism through which those catches happen.
• Security enforcement. A single unblocked SQL injection, hardcoded secret, or missing authentication check can lead to a data breach. Blocking comments ensure these issues are addressed before merge.
• Knowledge sharing. When a reviewer explains why something is a blocking issue, the author learns a pattern they will recognize in future work. Over time, this reduces the frequency of the same class of bug.
• Team trust. When blocking comments are reserved for genuinely critical issues, authors learn to trust the review process. They know that if a reviewer blocks, it matters — and they respond accordingly.

Best Practices

1. Reserve blocking status for issues that affect correctness, security, performance, or data integrity. If the code would work fine in production with the current approach, it probably should not be blocking.
2. Always explain the “why.” A blocking comment that says “fix this” without explanation breeds frustration. Explain the failure mode: “This will throw a NullPointerException when the user has no profile photo set.”
3. Provide a suggested fix when possible. Instead of just identifying the problem, show the solution. This accelerates the feedback loop and reduces back-and-forth.
4. Use a consistent labeling convention. Prefix blocking comments with blocking: or must-fix: so authors can triage feedback quickly and know exactly what they need to address before re-requesting review.
5. Re-review promptly after the author addresses your comments. Blocking a PR and then disappearing for three days defeats the purpose. Aim to re-review within a few hours of the author pushing fixes.

Common Mistakes

1. Treating style preferences as blocking issues. Insisting on a particular variable name, brace style, or import order as a blocking comment erodes trust and slows the team down. Use linters and formatters for style enforcement, and reserve blocking comments for substance.
2. Leaving blocking comments without a clear path to resolution. Vague comments like “this approach seems wrong” leave the author guessing. Every blocking comment should identify the specific problem, explain the risk, and ideally suggest an alternative.
3. Stacking too many blocking comments on a single PR. If a pull request has ten or more blocking issues, it may be a sign that the change was too large to review effectively or that alignment on the approach should have happened earlier. Consider requesting that the author break the PR into smaller pieces or schedule a synchronous design discussion.