What is the Commit Gate?

The commit gate is an optional feature in AI Diff Review that automatically reviews your code changes before you commit them. Based on the analysis results, it can recommend blocking a commit if it detects high-risk issues. This acts as an automated safety net, catching problems before they enter your repository.

The gate is designed to be intelligent and nuanced—it doesn't block every minor issue, but focuses on truly problematic changes that could cause security vulnerabilities, data loss, or severe functionality breakages.

How the Commit Gate Works

Weighted Scoring System

The commit gate uses a sophisticated weighted scoring system to evaluate the severity of findings. Different types of issues contribute different amounts to the total score:

  • Security Concerns: CRITICAL=5, WARNING=3, INFO=2
  • Critical Issues: CRITICAL=4, WARNING=3, INFO=2
  • Performance Notes: WARNING=1.5, INFO=0.5
  • Suggestions: WARNING=1, INFO=0.5
  • Code Quality: WARNING=1, INFO=0.5
  • Testing Recommendations: WARNING=0.5, INFO=0.25

This weighting ensures that security issues and critical problems have more impact on the decision than minor suggestions or style recommendations.

Severity Levels

The commit gate offers three severity levels that determine how strict the blocking behavior is:

INFO Level

Blocks commits when the total weighted score reaches 4.0 or higher. This is the most lenient setting, suitable for teams that want to catch only the most serious issues.

WARNING Level

Blocks commits when the total weighted score reaches 6.0 or higher. This provides a balanced approach, catching significant issues while allowing minor problems to pass through.

CRITICAL Level

Blocks commits when the total weighted score reaches 8.0 or higher, OR when any CRITICAL item is found in Security Concerns or Critical Issues categories. This is the strictest setting, ensuring that serious problems never make it into the repository.

Hard-Block Conditions

Certain conditions always trigger a block recommendation, regardless of the total score:

  • Any CRITICAL severity item in Security Concerns
  • High-risk security issues such as:
    • Secret leaks or exposed credentials
    • SQL injection vulnerabilities
    • Remote code execution (RCE) risks
    • Authentication bypass issues
    • Privilege escalation vulnerabilities

These hard-block conditions ensure that serious security vulnerabilities are never accidentally committed, even if the overall score is low.

Explicit AI Recommendations

In addition to the weighted scoring system, the AI model can explicitly recommend blocking a commit by setting should_block_commit=true in its response. When this happens, the plugin will recommend blocking the commit and provide the AI's reasoning in the block_reason field.

This allows the AI to make nuanced decisions based on context that might not be captured by the scoring system alone. For example, the AI might detect a pattern of issues that, while individually minor, collectively represent a significant problem.

Human-in-the-Loop Decision Making

The commit gate doesn't automatically prevent you from committing—it provides a recommendation and gives you the final say. When you attempt to commit with the gate enabled, you'll see a decision dialog that shows:

  • The gate's recommendation (BLOCK or PROCEED)
  • Total score and threshold
  • Count of findings by severity
  • Summary of key findings
  • Top contributing issues

This transparency helps you understand why a commit was flagged and make an informed decision. If you choose to proceed despite a BLOCK recommendation, you can provide a reason that will be appended to your commit message.

Configuring the Commit Gate

Enabling the Gate

To enable the commit gate, go to Settings → Tools → AI Diff Review and check "Enable pre-commit review". You can then select your preferred gate severity level.

Choosing the Right Level

The right severity level depends on your team's needs:

  • INFO: Good for teams just starting with automated review or those with very experienced developers
  • WARNING: Balanced option for most teams, catching significant issues without being overly restrictive
  • CRITICAL: Best for security-sensitive projects or teams that want maximum protection

Diff Scope Awareness

The commit gate is aware of diff scope settings. By default, only findings tied to changed lines (or within a small proximity window) contribute to scoring. Global or untargeted INFO items are typically ignored for gating purposes, ensuring that the gate focuses on issues actually introduced by your changes.

Best Practices

Start Conservative

If you're new to commit gates, start with INFO level and gradually increase strictness as your team becomes comfortable with the process. This helps avoid frustration from overly aggressive blocking.

Review Blocked Commits

When a commit is blocked, take time to review the findings. Even if you decide to proceed, understanding why it was flagged helps you learn and improve your code quality.

Use Override Reasonably

The ability to override a block recommendation is important for flexibility, but use it thoughtfully. If you frequently override blocks, consider whether your gate level is too strict or if there are patterns in your code that need addressing.

Team Communication

Make sure your team understands how the commit gate works and why certain commits are blocked. This helps build trust in the system and ensures everyone is aligned on code quality standards.

Conclusion

The commit gate is a powerful tool for maintaining code quality and security, but it's most effective when configured appropriately for your team's needs. By understanding how the weighted scoring works and choosing the right severity level, you can create an effective safety net that catches problems without becoming a bottleneck.

Remember, the gate is there to help, not to hinder. Use it as a tool to improve code quality while maintaining developer productivity. With proper configuration and team buy-in, the commit gate becomes an invaluable part of your development workflow.

Ready to set up your commit gate? Install AI Diff Review and start protecting your codebase today.