Size Limits
Overview
The Size Limits validator enforces constraints on merge request size to keep changes manageable and reviewable. It can limit the number of files changed, lines changed, and commits.
Configuration
Optional Properties
maxFiles: Maximum number of files that can be changed (integer, default:null)maxLines: Maximum total lines changed (additions + deletions) (integer, default:null)maxCommits: Maximum number of commits in the MR (integer, default:null)excludeRenames: Exclude renamed files from file and line counts (boolean, default:false)excludeDeleted: Exclude deleted files from file and line counts (boolean, default:false)severities: Controls violation severity and early-warning threshold (SizeLimitsSeverityConfig, default: see sub-properties below); a scalarseverity:sets the severity of every finding of the ruleonViolation: Severity when a limit is reached:"error"or"warning"(string, default:"error")warnThreshold: Optional early-warning threshold as a percentage of the limit. When set, a warning finding is emitted if usage exceedslimit * warnThresholdbut is below the hard limit. Must be between 50% and 99% if provided (percentage, default:null)
Examples
Basic Usage - File Limit
karandash {
rules {
sizeLimits {
maxFiles = 20
}
}
}
Line Limit
karandash {
rules {
sizeLimits {
maxLines = 500
}
}
}
Commit Limit
karandash {
rules {
sizeLimits {
maxCommits = 10
}
}
}
Combined Limits
karandash {
rules {
sizeLimits {
maxFiles = 30
maxLines = 1000
maxCommits = 15
}
}
}
Strict Limits for Small Changes
karandash {
rules {
sizeLimits {
maxFiles = 10
maxLines = 300
maxCommits = 5
}
}
}
Error Messages
- Too many files:
Too many files changed: {count} (max: {max}) - Too many lines:
Too many lines changed: {count} (max: {max}) - Too many commits:
Too many commits: {count} (max: {max})
The suggestion carries the numbers: Split the MR: {count} {metric} is {count - max} over the limit of {max}.; an
"Approaching" warning suggests Keep the MR at or under {max} {metric}: {max - count} more allowed, or split it.
Best Practices
When to Use This Rule
- Encourage focused, reviewable changes
- Prevent massive "catch-all" merge requests
- Improve code review quality
- Reduce review fatigue
- Enforce incremental development
Recommended Limits
Small Team / High Velocity:
sizeLimits {
maxFiles = 15
maxLines = 400
maxCommits = 8
}
Medium Team / Standard Projects:
sizeLimits {
maxFiles = 25
maxLines = 800
maxCommits = 12
}
Large Team / Complex Projects:
sizeLimits {
maxFiles = 40
maxLines = 1500
maxCommits = 20
}
Strict Policy (Recommended):
sizeLimits {
maxFiles = 20
maxLines = 500
maxCommits = 10
}
Guidelines by Change Type
Bug Fixes:
sizeLimits {
maxFiles = 5
maxLines = 200
maxCommits = 3
}
Features:
sizeLimits {
maxFiles = 30
maxLines = 1000
maxCommits = 15
}
Refactoring:
sizeLimits {
maxFiles = 50 // May touch many files
maxLines = 2000 // But mostly moves, not new logic
maxCommits = 10
}
Tips
- Start with generous limits, tighten based on team feedback
- Document why limits exist (review quality, maintainability)
- Provide guidance on splitting large changes
- Use exceptions for special cases (generated code, migrations)
- Monitor actual MR sizes to calibrate limits
Understanding Line Count
maxLines counts additions + deletions:
+ 100 lines added
- 50 lines deleted
= 150 total lines changed
This measures the scope of review rather than net change.
When Limits Are Exceeded
Strategies for Developers
Split by Component:
MR 1: Backend API changes
MR 2: Frontend UI changes
MR 3: Tests and documentation
Split by Feature:
MR 1: Core feature implementation
MR 2: Edge case handling
MR 3: Performance optimizations
Split by Dependency:
MR 1: Database schema changes
MR 2: Backend service updates
MR 3: Frontend integration
Guidance for Teams
Add this to your CONTRIBUTING.md:
## Merge Request Size Limits
- Maximum 20 files changed
- Maximum 500 lines changed
- Maximum 10 commits
If your change exceeds these limits:
1. Split into logical, independent MRs
2. Create a tracking issue linking all related MRs
3. Submit MRs in dependency order
4. Request limit exception from tech lead (rare cases)
Combining with Other Rules
With Conditional Rules
policies {
largeRefactor {
when = "label_exists(\"large-refactor\")"
modules = listOf("sizeLimits")
override {
sizeLimits {
maxFiles = 100 // Relaxed for refactoring
maxLines = 3000
}
}
}
}
With Labels
rules {
sizeLimits {
maxFiles = 20
maxLines = 500
}
labels {
conditionalLabels = listOf(
ConditionalLabel(
condition = LabelCondition(hasLabel = "large-change"),
requiredLabels = listOf("split-approved", "tech-lead-review")
)
)
}
}
Exceptions and Special Cases
Generated Code
// Document in guidelines:
// "Generated code (e.g., proto files, migrations) may exceed limits.
// Add 'generated-code' label and get approval from tech lead."
Database Migrations
// Large data migrations may need exceptions
// Use conditional rules or manual approval process
Dependency Updates
// Package-lock.json changes can be large
// Consider excluding from line count or using separate validation
Initial Implementation
// First implementation of major feature may be larger
// Use 'initial-implementation' label and require extra review
Benefits of Size Limits
For Reviewers: - Manageable review scope - Better focus and attention - Faster review turnaround - Lower cognitive load
For Authors: - Clearer change boundaries - Easier to describe changes - Faster feedback cycles - Simpler conflict resolution
For Teams: - Higher review quality - More frequent integration - Reduced merge conflicts - Better commit history
Monitoring and Metrics
Track these metrics to calibrate limits:
- Average MR size (files, lines, commits)
- Review time vs. MR size correlation
- Defect rate vs. MR size correlation
- MRs exceeding limits (frequency)
What Counts as a File Change?
- Added files: Count toward limit
- Modified files: Count toward limit
- Deleted files: Count toward limit
- Renamed files: Typically count as 2 (delete + add)
Commit Count Considerations
High commit count may indicate: - Work-in-progress commits not squashed - Multiple logical changes in one MR - Long-running feature branch - Incremental development (good!)
Encourage:
- Squash WIP commits before review
- Keep commits atomic and meaningful
- Follow conventional commit format
Common Threshold Values
maxFiles:
5 - Very strict (bug fixes only)
10 - Strict (focused changes)
20 - Moderate (recommended)
30 - Lenient (features)
50+ - Very lenient (refactors, migrations)
maxLines:
200 - Very strict
500 - Strict (recommended)
1000 - Moderate
2000 - Lenient
5000+ - Very lenient (special cases)
maxCommits:
3 - Very strict (encourage squashing)
5 - Strict
10 - Moderate (recommended)
20 - Lenient
50+ - Very lenient (feature branches)
Related Rules
- Commit Messages - Validate commit quality
- Labels - Label large changes appropriately
- Conditional Rules - Context-specific limits
- File Changes - Monitor specific file patterns