Rules Reference
Karandash provides 21 built-in validation rules for merge requests. Each rule is highly configurable and can be enabled/disabled independently.
Available Rules
Title & Description
- Title Format - Validate MR title format, length, and patterns
- Commit Messages - Validate commit message format (conventional commits)
- JIRA Ticket - Require and validate JIRA ticket references
- Description Format - Validate MR description structure and content
- Context Tags - Validate context tag conventions
Branch & Labels
- Branch Naming - Enforce branch naming conventions
- Labels - Require or forbid specific labels on MRs
Files & Changes
- File Changes - Monitor specific file patterns and enforce requirements
- Size Limits - Limit the size of changes (files, lines, commits)
- Security - Scan for secrets and sensitive file changes
Approvals & Reviewers
- Approvals - Require minimum approvals and specific approvers
- Reviewers - Enforce reviewer requirements
- Codeowners - Validate CODEOWNERS compliance
CI/CD & Status
- CI/CD Status - Require passing CI/CD pipelines
- Conflict Detection - Block MRs with merge conflicts
- Draft Detection - Block or warn on draft/WIP MRs
Integration & Intelligence
- AI-powered Rules - AI review via Anthropic, OpenAI, Ollama
- JIRA Validation - JIRA ticket validation and enrichment (beyond basic reference checks)
- Cross-entity Consistency - Validate consistency across related entities
- Language Policy - Enforce language policy rules
Advanced
- Conditional Rules - Apply rules conditionally based on MR properties
Opt-in rules
cicdStatus, contextTag, crossEntity and languagePolicy do nothing until you configure them: they are not part of the default rule set, so a config that never mentions them never runs them. Add the rule's block (see its page above) to turn it on. The AI rules are opt-in too; see AI-powered Rules.
Suppressing findings
- In the MR description: a line
karandash-disable <rule>drops every finding of that rule for this MR, for examplekarandash-disable sizeLimits(size-limitsandsize_limitswork too) to override the size limits for one MR. Several rules can be listed with commas (karandash-disable sizeLimits, labels). Text after the first rule id on a line is ignored. Anyone who can edit the description can use it, so do not rely on it for rules that must hold. - Baseline:
karandash validate --baseline findings-baseline.jsonignores findings whose fingerprint is in the file.--baseline findings-baseline.json --update-baselinerewrites the file from the current findings. The file can also be set once withbaseline: findings-baseline.jsonin the config (the flag wins);--update-baselinewithout either exits 2. A baseline file that is not valid JSON of the expected shape is a config error (exit 2). The JSON report'sbaselineComparisonthen counts new, resolved and unchanged findings.
All rules are configured in the karandash.kts configuration file using Kotlin DSL:
karandash {
rules {
titleFormat {
pattern = "^(feat|fix|docs|chore): .+"
minLength = 10
maxLength = 72
}
approval {
minApprovals = 2
requiredApprovers = listOf("tech-lead", "architect")
}
// ... more rules
}
}
Common Properties
Most rules share these common configuration patterns:
- Pattern Matching: Rules that validate text use regex patterns
- List-based Requirements: Rules can require or forbid specific values
- Conditional Logic: Many rules support conditional requirements
Universal Rule Options
Every rule supports two optional fields that improve the developer experience when violations are found:
| Option | Type | Default | Description |
|---|---|---|---|
suggestion |
String |
null |
A short, actionable hint shown to the MR author when this rule fails. Displayed in console output, MR comments, and IDE integrations. |
explanation |
String |
null |
A longer explanation of why the rule exists. Shown with --explain or in verbose reporters. |
Example (Kotlin DSL):
rules {
titleFormat {
pattern = "^(feat|fix|docs):"
suggestion = "Use 'feat: ...', 'fix: ...', or 'docs: ...' as your title prefix"
explanation = "Conventional commit prefixes enable automated changelogs and semantic versioning"
}
}
Example (YAML):
rules:
title-format:
pattern: "^(feat|fix|docs):"
suggestion: "Use 'feat: ...', 'fix: ...', or 'docs: ...' as your title prefix"
explanation: "Conventional commit prefixes enable automated changelogs and semantic versioning"
Rule Execution
Rules are executed in the following order:
- Basic validation (title, description, branch naming)
- Content validation (commits, file changes)
- People validation (approvals, reviewers, codeowners)
- Status validation (CI/CD, conflicts, draft)
- Security validation (secrets, sensitive files)
- Conditional rules (based on MR properties)
Severity Levels
Findings from rules can have different severity levels:
- ERROR: Blocks merge, must be resolved
- WARNING: Advisory, doesn't block merge
- INFO: Informational, for awareness only
Next Steps
- Browse individual rule documentation for detailed configuration options
- See Quick Start for configuration examples
- Learn about Creating Plugins for custom validation logic