Skip to main content

PR Anlaysis Configuration

CodeSherlock Configuration Setup Guide for Pull Request Reviews

Overview​

This guide explains how to configure CodeSherlock using the codesherlock.yaml configuration file for Pull Request Reviews. This file should be placed inside the .github folder, which is located in the root of your repository, to customize the automated code review behavior.

File Location​

Place the codesherlock.yaml file inside a .github folder, and that .github folder must be located in the root directory of your repository.

your-repository/
├── .github/
│   └── codesherlock.yaml
├── src/
├── README.md
└── ...

Download Configuration Template

Click the link below to download the configuration template. Use it as a baseline for customizing your setup:

codesherlock.yaml template file

Configuration Options​

1. Target Branches​

Define which branches should trigger code reviews when pull requests target them.

target_branches: ["main", "develop"]

Options:

  • Array of strings: List branch names that should trigger reviews
  • Default behavior: If this section is removed, reviews will run for ALL pull requests regardless of target branch
  • Common examples: ["main"], ["main", "develop", "staging"], ["master", "production"]

2. Preferred Characteristics​

Specify which code quality characteristics the review should focus on.

preferred_characteristics: ["Modularity", "Resource Utilization", "Exception Handling", "Monitoring and Logging", "Dependency Injection", "Code Injection", "Input Validation"]

Available Characteristics:

  • Modularity - Code organization and separation of concerns
  • Resource Utilization - Memory and performance efficiency
  • Exception Handling - Error handling and recovery mechanisms
  • Monitoring and Logging - Observability and debugging capabilities
  • Dependency Injection - Loose coupling and testability
  • Code Injection - Security vulnerabilities related to code execution
  • Input Validation - Data sanitization and security checks

Configuration Notes:

  • Customizable: Remove any characteristics you don't want to focus on
  • Extensible: Adding items outside this list won't affect the review
  • Default behavior: If this section is removed, all 7 default characteristics will be used

3. Additional Instructions (Optional)​

Add custom rules and specific checks for your codebase.

additional_instructions:
  - No exposed secrets or API keys
  - No console.log, print, System.out.println left in code
  - Follow company naming conventions
  - Include unit tests for new features

Usage:

  • Each instruction should be on a separate line with a dash (-)
  • Optional section: If removed, only default review checks will be applied
  • Examples of custom rules:
    • Security checks (no hardcoded credentials)
    • Code cleanliness (no debug statements)
    • Style guidelines
    • Testing requirements
    • Documentation standards

Complete Configuration Example​

# Trigger reviews for PRs targeting these branches
target_branches: ["main", "develop"]

# Focus review on these quality characteristics
preferred_characteristics: 
  - "Modularity"
  - "Resource Utilization" 
  - "Exception Handling"
  - "Monitoring and Logging"
  - "Dependency Injection"
  - "Code Injection"
  - "Input Validation"

# Custom rules specific to your project
additional_instructions:
  - No exposed secrets or API keys
  - No console.log, print, System.out.println left in code
  - All public methods must have documentation
  - Include error handling for external API calls
  - Use dependency injection for database connections

Minimal Configuration Examples​

Basic Setup (Main Branch Only)​

target_branches: ["main"]

Security-Focused Review​

target_branches: ["main", "develop"]
preferred_characteristics: ["Code Injection", "Input Validation", "Exception Handling"]
additional_instructions:
  - No hardcoded passwords or API keys
  - Validate all user inputs
  - Use parameterized queries for database operations

Performance-Focused Review​

target_branches: ["main"]
preferred_characteristics: ["Resource Utilization", "Modularity"]
additional_instructions:
  - Avoid nested loops where possible
  - Use appropriate data structures
  - Include performance tests for critical paths

Setup Steps​

  1. Create the file: Add codesherlock.yaml to your repository root
  2. Configure branches: Set your target branches (typically main and/or develop)
  3. Select characteristics: Choose which code quality aspects to focus on
  4. Add custom rules: Include any project-specific requirements
  5. Commit and push: Add the configuration file to version control
  6. Test: Create a test PR to verify the configuration works as expected

YAML Syntax Reference​

For detailed YAML syntax information, refer to the official YAML specification and the YAML syntax guide.

Key YAML concepts used in this configuration:

  • Arrays: Use square brackets [] or dash notation for lists
  • Strings: Quoted or unquoted text values
  • Multi-line strings: Use | for literal blocks
  • Comments: Lines starting with # are ignored

Troubleshooting​

Common Issues:

  • Invalid YAML syntax: Use a YAML validator to check formatting
  • Reviews not triggering: Verify branch names match exactly
  • Unexpected behavior: Check that all sections are properly indented
  • Custom rules ignored: Ensure additional_instructions uses proper YAML literal block format

Testing Your Configuration:

  1. Validate YAML syntax using online tools
  2. Create a test PR to verify behavior
  3. Check review output matches expected characteristics
  4. Adjust configuration as needed