YAML Configuration Guide
YAML configuration provides a simpler, more portable alternative to the Kotlin DSL for teams that prefer declarative configuration. This guide covers the complete YAML schema, environment variable interpolation, config inheritance, and migration from Kotlin DSL.
Quick Start
Create .karandash/config.yaml in your repository root:
rules:
title-format:
pattern: "^(feat|fix|chore|docs):.*"
min-length: 10
max-length: 120
size-limits:
max-lines: 500
max-files: 30
reporters:
console: true
Run validation:
karandash validate
That's it. Karandash auto-discovers .karandash/config.yaml or .karandash/config.yml.
YAML vs Kotlin DSL
| Feature | YAML | Kotlin DSL |
|---|---|---|
| Syntax | Declarative YAML | Kotlin-like DSL |
| Ease of Use | Simple, no programming knowledge | Requires basic Kotlin familiarity |
| Environment Variables | ${VAR} syntax |
env.VAR syntax |
| Config Inheritance | extends: "url" |
Supported |
| Type Safety | Runtime validation | Compile-time validation (via parser) |
| IDE Support | YAML schema validation | Limited (no LSP yet) |
| Portability | Works anywhere | JVM + Native |
| Best For | Simple setups, CI templates | Complex logic, Kotlin teams |
Recommendation: Use YAML for most projects. Use Kotlin DSL only if you need programmatic logic or are already a Kotlin shop.
Complete YAML Schema
Important: There is NO separate top-level
auth:block in Karandash configuration. Authentication credentials are configured inline within theplatforms:block. Anyauth:block you create will be ignored.
Provider Configuration (with Authentication)
Configure platform providers with inline authentication:
platforms:
# GitLab
gitlab:
url: "https://gitlab.com"
token: "${GITLAB_TOKEN}"
# GitHub
github:
token: "${GITHUB_TOKEN}"
base-url: "https://api.github.com" # Optional, for GitHub Enterprise
# Bitbucket
bitbucket:
token: "${BITBUCKET_TOKEN}"
# Azure DevOps
azure-devops:
token: "${AZURE_DEVOPS_TOKEN}"
organization: "my-org"
# Gerrit
gerrit:
url: "https://gerrit.example.com"
username: "${GERRIT_USERNAME}"
token: "${GERRIT_TOKEN}"
# Gitea
gitea:
url: "https://gitea.example.com"
token: "${GITEA_TOKEN}"
# AWS CodeCommit
# Omit the keys to use AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or ~/.aws (optional `profile:`)
aws-codecommit:
region: "us-west-2"
access-key-id: "${AWS_ACCESS_KEY_ID}"
secret-access-key: "${KARANDASH_AWS_SECRET_ACCESS_KEY}"
Validation Rules
Title Format
rules:
title-format:
pattern: "^(feat|fix|chore|docs|test|refactor|style|perf)(\\(.*\\))?:.*"
min-length: 10
max-length: 120
require-ticket: false # If true, title must contain JIRA ticket
Commit Messages
rules:
commit-messages:
format: "conventional" # or "custom"
pattern: "^(feat|fix|chore):.*" # Used when format is "custom"
min-length: 10
max-length: 100
JIRA Ticket Validation
rules:
jira-ticket:
project-keys:
- "PROJ"
- "TASK"
pattern: "[A-Z]+-[0-9]+"
validate-status:
- "In Progress"
- "In Review"
validate-assignee: false
Branch Naming
rules:
branch-naming:
pattern: "^(feature|bugfix|hotfix|release)/.*"
allowed-patterns:
- "^feature/.*"
- "^bugfix/.*"
- "^hotfix/.*"
require-source-match: true # Source branch must match pattern
require-target-match: false # Target branch (e.g., main) exempt
File Changes
rules:
file-changes:
require-approval: ["database-team"] # Global approval requirement
require-labels: ["needs-review"] # Global label requirement
block-on-draft: off # Block file changes in draft MRs
patterns: # Path-based rules
- pattern: "**/*.sql"
require-approval: ["database-team"]
require-labels: ["database-change"]
block-on-draft: fail
CODEOWNERS
rules:
codeowners:
path: ".github/CODEOWNERS" # or "CODEOWNERS"
require-owner-approval: true
Approval Requirements
rules:
approval:
min-approvals: 2
required-approvers:
- "tech-lead"
- "senior-dev"
no-changes-since-approval: true # Resets approvals on new commits
Reviewer Requirements
rules:
reviewer:
required-reviewers:
- "senior-dev-1"
required-teams:
- "backend-team"
excluded-reviewers:
- "bot-user"
CI/CD Status
rules:
cicd-status:
require-passed: true
required-jobs:
- "build"
- "test"
- "lint"
block-on-failing: fail
Merge Conflicts
rules:
conflict:
block-on-conflicts: fail
Draft/WIP Detection
rules:
draft:
block-draft: fail
wip-patterns:
- "WIP"
- "\\[WIP\\]"
- "wip:"
- "WIP:"
Labels
rules:
labels:
required-labels:
- "reviewed"
forbidden-labels:
- "do-not-merge"
- "wip"
conditional-labels: # Advanced: conditional label rules
- condition:
has-label: "breaking-change"
required-labels:
- "changelog-updated"
- condition:
has-any-label: ["feature", "enhancement"]
forbidden-labels:
- "needs-design"
Size Limits
rules:
size-limits:
max-files: 50
max-lines: 500
max-commits: 20
Security Scanning
rules:
security:
scan-for-secrets: true
secret-patterns:
- "(?i)(password|passwd|pwd)\\s*=\\s*['\"][^'\"]+['\"]"
- "(?i)(api[_-]?key|apikey)\\s*=\\s*['\"][^'\"]+['\"]"
sensitive-files:
- "**/.env"
- "**/.env.*"
- "**/*.pem"
- "**/*.key"
Boolean shorthand
rules: { commit-messages: true } runs the rule with its default config; false disables it.
Policies
Policies are conditional overrides that apply when a when: expression evaluates to true
for the current MR. They can enable/disable modules, override rule configs, change finding
severity, and gate pipeline stages - all without duplicating configuration.
Basic structure
policies:
- when: '<condition expression>'
modules: [module-id, ...] # Optional: scope to specific modules; omit for all modules
enabled: false # Optional: enable or disable matched modules
severity: warning # Optional: override finding severity (info/warning/error)
override: # Optional: deep-merged into matched module configs
rule-name:
key: value
autoApprove: false # Optional: gate the auto-approve pipeline stage
autoFix: false # Optional: gate the auto-fix pipeline stage
scripts: false # Optional: gate the scripts pipeline stage
dangerfile: false # Optional: gate the Dangerfile execution stage
modules:
The modules: field scopes a policy to specific module IDs. It accepts any module type:
rules, reporters, enrichment providers, AI analyzers, etc.
- when: 'is_draft'
modules: [ai-risk-scoring]
enabled: false
Pipeline stage control
Four boolean fields gate whether specific pipeline stages execute when the policy matches:
| Field | Stage controlled |
|---|---|
autoApprove |
Automatic MR approval by Karandash |
autoFix |
Automatic fix application (e.g. label mutations) |
scripts |
External script execution (.karandash/scripts/) |
dangerfile |
Dangerfile execution |
policies:
# Never auto-approve MRs targeting main
- when: 'target_branch_matches("^(main|master)$")'
autoApprove: false
# Do not mutate draft MRs
- when: 'is_draft'
autoFix: false
scripts: false
dangerfile: false
Condition expression predicates
Condition expressions are boolean expressions using the predicates below. Operators:
&& (and), || (or), ! (not), parentheses for grouping, >, <, >=, <=, ==
for numeric comparisons.
MR state - bare predicates (no arguments)
| Predicate | True when |
|---|---|
is_draft |
MR is marked as draft/WIP |
has_description |
MR description is non-empty |
has_approvals |
At least one approval exists |
has_reviewers |
At least one reviewer is assigned |
has_conflicts |
MR has merge conflicts |
is_merged |
MR state is merged |
is_closed |
MR state is closed |
is_opened |
MR state is open |
has_ci |
MR has at least one CI pipeline |
MR numeric comparisons
Syntax: predicate > N, predicate < N, predicate >= N, predicate <= N, predicate == N
| Predicate | Measures |
|---|---|
change_count |
Number of changed files |
additions |
Total added lines |
deletions |
Total deleted lines |
total_changes |
Total added + deleted lines |
commit_count |
Number of commits |
approval_count |
Number of approvals |
reviewer_count |
Number of assigned reviewers |
label_count |
Number of labels |
description_length |
Character length of the description |
mr_age_hours |
MR age in hours (since earliest commit) |
mr_age_days |
MR age in days (since earliest commit) |
last_commit_age_hours |
Hours since the most recent commit |
- when: 'change_count > 50 || mr_age_days > 14'
severity: error
MR field matching
| Predicate | Arguments | Matches against |
|---|---|---|
title_matches("pattern") |
regex | MR title |
branch_matches("pattern") |
regex | Source branch |
branch_matches("pattern", "target") |
regex, "target" |
Target branch |
source_branch_matches("pattern") |
regex | Source branch |
target_branch_matches("pattern") |
regex | Target branch |
author_matches("pattern") |
regex | MR author username |
description_matches("pattern") |
regex | MR description |
commit_message_matches("pattern") |
regex | Any commit message |
commit_author_matches("pattern") |
regex | Any commit author email |
label_exists("name") |
string | Label list (case-insensitive) |
label_matches("pattern") |
regex | Label list |
approved_by("username") |
string | Approval list (case-insensitive) |
reviewer_is("username") |
string | Reviewer list (case-insensitive) |
ci_status("status") |
string | CI pipeline status (case-insensitive) |
ci_job_status("job", "status") |
strings | Specific CI job status |
merge_status("status") |
string | Platform merge status string |
- when: 'target_branch_matches("^main$") && !approved_by("tech-lead")'
modules: [approval]
override:
approval:
minApprovals: 2
File predicates
| Predicate | Arguments | True when |
|---|---|---|
file_path_matches("glob") |
glob | Any changed file path matches the glob |
has_changes_in("prefix") |
string | Any changed file path starts with prefix |
file_extension_matches(".ext") |
string | Any changed file has the extension |
file_modified("path") |
string | A specific file path is in the diff |
file_added("pattern") |
string | A newly-added file path contains the pattern |
has_file_type(".ext") |
string | Same as file_extension_matches |
change_type_exists("ADDED\|MODIFIED\|DELETED") |
string | Any change has that type |
file_count > N |
comparison | Changed file count comparison |
file_count_added > N |
comparison | Added-file count comparison |
file_count_deleted > N |
comparison | Deleted-file count comparison |
file_count_modified > N |
comparison | Modified-file count comparison |
- when: 'file_extension_matches(".sql") || file_modified("db/schema.rb")'
override:
labels:
requiredLabels: ["database-approved"]
Environment predicates
| Predicate | Arguments | True when |
|---|---|---|
is_ci |
- | The CI environment variable is set |
is_gitlab_ci |
- | Running inside GitLab CI |
is_github_actions |
- | Running inside GitHub Actions |
ci_platform("name") |
string | CI platform matches name (case-insensitive) |
env_set("VAR") |
string | Environment variable is set (non-null) |
env_equals("VAR", "value") |
strings | Variable equals the given value |
env_matches("VAR", "pattern") |
regex | Variable matches the regex |
- when: '!is_ci'
modules: [slack-webhook]
enabled: false
- when: 'env_set("STRICT_REVIEW")'
override:
size-limits:
maxFiles: 30
maxLines: 800
Config predicates
| Predicate | Arguments | True when |
|---|---|---|
is_dry_run |
- | Top-level dry-run: true is set (see Dry run) |
has_profile |
- | A profile is active (any profile) |
profile_is("id") |
string | Active profile ID equals the value |
module_configured("id") |
string | Module is present in config |
- when: 'profile_is("strict")'
override:
approval:
minApprovals: 2
- when: 'is_dry_run'
severity: info
ConditionContext
The evaluation context passed to every predicate is ConditionContext. Plugin authors implementing custom predicates via
Module.registerPredicates() should import io.karandash.api.context.ConditionContext.
Key fields available in ConditionContext:
| Field | Type | Description |
|---|---|---|
mr |
MergeRequest |
The fetched MR (changes, commits, labels, approvals, etc.) |
isCI |
Boolean |
Whether running in a CI environment |
ciPlatform |
String? |
Detected CI platform name ("gitlab", "github", …) |
dryRun |
Boolean |
Whether top-level dry-run: true is set |
profileId |
String? |
Active profile ID, or null if none |
configuredModuleIds |
Set<String> |
IDs of all modules present in config |
nowEpochSeconds |
Long |
Current time as Unix epoch seconds (for age predicates) |
env(name) |
String? |
Reads from the allowlisted environment variable set |
Shadow mode (severity-cap)
Roll out a new preset without blocking merges: severity-cap: lowers every finding that is more severe than the
cap to the cap, so the run reports what would fail but passes. A per-rule severity-cap: caps one rule and wins
over the top-level value; error there keeps that rule blocking while the rest is capped. No cap (the default)
changes nothing.
severity-cap: warning # every rule reports at most a warning
rules:
title-format:
severity-cap: error # still blocks
commit-messages:
severity-cap: info # reported as info only
The cap runs after every other post-validation step (AI findings included), and the exit code, auto-approve and
the reported severities follow the capped values. It is the severity-cap pipeline extension
(io.karandash.extensions.SeverityCapExtension), built in and active only when a cap is set.
Dry run
dry-run: true # sets is_dry_run and makes an AI dry run
dry-run-scope: ai # optional: ai | all
dry-run-scope |
Effect (only with dry-run: true) |
|---|---|
| unset (default) | Same as ai, with a one-time warning (before, dry-run alone only fed is_dry_run). |
ai |
AI rules make no LLM calls and @karandash why/ask post no thread replies (same as ai.dryRun: true); every other rule and output runs. |
all |
ai plus: outputs with external side effects (platform comments, Slack, webhook, email, third-party outputs) and auto-approve are skipped with a dry-run: skipped <id> info line. Console and file outputs still run. |
Not the same as the --dry-run CLI flag, which only validates the config.
Network access (SSRF protection)
Every outbound URL (platforms, webhooks, AI providers, remote extends:) must be HTTPS and point to a public
host; host names are also resolved before each request and rejected if they resolve to a non-public address.
allow-private-network: true # self-hosted services on an internal network
# allow-localhost: true # local development only: lifts every check below
| Host | default | allow-private-network: true |
allow-localhost: true |
|---|---|---|---|
| Public | allowed | allowed | allowed |
Private (10/8, 172.16/12, 192.168/16, 100.64/10, 198.18/15, fc00::/7) or dotless (gitlab), literal or after DNS |
blocked | allowed | allowed |
Loopback (localhost, 127/8, ::1) |
blocked | blocked | allowed |
Cloud metadata, link-local (169.254/16, fe80::/10), obfuscated numeric hosts |
blocked | blocked | allowed |
http:// as the configured URL |
blocked | blocked | allowed |
IPv6 forms that carry an IPv4 address (::ffff:a00:1, ::10.0.0.1, NAT64 64:ff9b::/96, 6to4 2002::/16) are
classified as that IPv4 address. On the native binaries a host name whose lookup fails for any reason other than "no
such name" (resolver down, timeout) is refused rather than passed unchecked.
allow-private-network is the narrow escape hatch for git.example.corp → 10.x.x.x: it keeps the metadata, link-local
and loopback checks. It applies to the whole run and to every outbound request (platforms, webhooks, AI providers,
remote cache, extends:, plugin content), not per service. It does not change scheme rules: a configured webhook,
platform or provider URL must still be https://, but the per-request check (which also runs on redirect targets)
accepts http:// for any host it permits - public hosts always, private hosts under this flag - so a redirect to
http://10.x.x.x is followed. Key spellings allow_private_network and allowPrivateNetwork work too.
An extends: parent's allow-private-network counts like the root's own (the root can still set false). Fetching
the extends: chain inherits it step by step: a parent's value applies to fetching its own parents unless a layer
closer to the root sets it. allow-localhost inherits the same way. Each run (and each
--watch re-run, doctor, validate-extends) sets it afresh, so a run without it has it off.
Limits
DoS guards. Every value is clamped to safe bounds; an out-of-bounds value is replaced by the nearest bound with a warning. Unset keeps the built-in default.
limits:
max-findings: 10000 # findings kept per run (100..100000)
fetch-timeout: "10s" # remote extends / { file: } fetches (1s..120s)
expressions:
max-length: 1000 # when:/policy expressions (100..10000)
max-nesting-depth: 50 # (5..200)
extends:
max-entries: 10 # extends entries per file (1..50)
max-depth: 5 # inheritance depth (1..20)
max-chain-size: 20 # configs in the whole chain (2..100)
regex:
max-pattern-length: 500 # user regex length (50..2000)
max-quantifier-nesting: 1 # nested quantifiers allowed (1..3)
patterns:
max-expansion-depth: 20 # nested named-pattern expansion (5..50)
limits.fetch-timeout, limits.extends and limits.glob (glob extends: entries) bound the resolution of the config
chain itself. They inherit like any other key, step by step: each layer's parents are fetched under the value merged from the root down to that layer (the closer layer wins, the root over everything). A parent can raise
or lower them for the rest of the chain, always within the bounds above. cache.downloads, allow-localhost and
allow-private-network inherit the same way while the chain is fetched. ${VAR} values count after interpolation,
as in the run. A config reachable by several paths (a diamond) is fetched once, under the values inherited on the
path closest to the root; between paths of equal depth, the one through the later-declared extends: entry wins
(the same entry whose values win the merge).
Remote extends: configs are cached across runs in the downloads cache (~/.karandash/cache, keyed by the
normalized URL, revalidated with ETag where the server sends one, bounded by the cache size limit and GC).
cache.downloads.ttl sets the freshness window (default 1d). cache.downloads.enabled: false, cache.enabled: false
and --no-cache fetch every remote config directly and write nothing to the cache dir.
Display
display:
watcher:
debounce: "500ms" # --watch debounce (0..60s)
console:
success-mark: "OK" # console format marks; reporters.console.success-mark wins
failure-mark: "FAIL"
display.git.short-sha-length (clamped to 4..40, default 7) sets the abbreviated commit SHA in finding text. The SHA is part of the message, so changing it changes message-based dedup and baseline keys.
Report language
report:
language: ru # BCP-47 tag, default en; ru-RU reads as ru
report.language sets the output language of the AI messages and summaries. It inherits through extends:.
A region tag maps to its base tag (ru-RU reads as ru).
The markdown MR summary (headings, status, tables, collapsed lists, checklist, footer) and the inline-review lines of
the platform summary are written in English; every other language comes from a translation pack (Russian, ru, and
Polish, pl, ship built in, see Language packs); a language without a pack renders them in English. A reporters:
entry may set its own language to override it for that format or output. Finding messages come from the rules (or the
AI, see below), rule ids stay as they are, and inline comment bodies keep their English severity words so later runs
still match their threads. Other formats (console, html, slack, ...) are not localized.
For any language but English, every AI prompt carries one instruction that is never trimmed under a tight budget: reason in English, write the finding messages and the summary in the report language, keep code, identifiers, paths and suggestion blocks verbatim, and never report the natural language of the MR content as a finding. The deterministic language-policy rule is unaffected: it checks only the MR title, description, commits and branch name.
ai.response-language (also response_language, responseLanguage) is an alias of report.language: set on its own, it
works without a warning, also when only a parent sets it. A blank value counts as unset. Across
extends: the nearest config that sets either key wins (the root before its parents), so a child's alias overrides a
parent's report.language and the other way round; within one file report.language wins, and a warning names both
values only when one file sets both.
Language packs
A language beyond en is a plugin module of type TRANSLATION (TranslationModule in plugins/sdk). It is
data only: language (a base tag such as pl), pluralRule (ONE_OTHER, EAST_SLAVIC or WEST_SLAVIC) and
translations(), a map from each English template to its text, gettext style. Placeholders ({0}, {1}, %d) stay as
they are, and a counted text keeps its one|few|many forms separated by |. Any English template missing from the map
renders in English. Packs load at startup with the other plugins (JAR, JS, WASM or native; the bridges carry the map in
the module descriptor), and a pack for en is ignored. Two packs ship built in and load by default: Russian
(io.karandash.translation.ru, EAST_SLAVIC) and Polish (io.karandash.translation.pl). Russian used to be compiled
into every text table; it moved into its pack unchanged, and stays bundled because dropping it would break every config
with report.language: ru. Code that renders texts without the plugin bootstrap (an embedder, a unit test) gets English
for ru until it calls RussianTranslationModule.register().
Reporters
reporters:
console: true
markdown: true # Post compliance summary, inline comments, and AI suggestions on MR/PR
slack:
webhook: "${SLACK_WEBHOOK_URL}"
channel: "#code-reviews"
sarif:
output-file: "karandash-results.sarif"
Report transparency
report:
transparency:
summary: collapsed # off | collapsed (default) | expanded
inline-why: false # one-line "why" footer under each inline note
flow-diagram: false # Mermaid flow diagram of the run inside the block
walkthrough: off # off (default) | collapsed: changes table in the AI MR summary
When an AI rule ran, the markdown summary ends with a <details> block "How this review was made": coverage
with what was left out of the diff and of the context, each enricher (ok, skipped with why, e.g. a missing
JIRA_TOKEN or no ast-grep, or failed), each analyzer (model, tokens in/out, cost, findings) and how many findings
each filter removed, feedback suppressions included. summary: expanded opens it; summary: off gives the summary
exactly as before. Runs without an AI rule show no block.
inline-why: true ends each AI inline note with Why: ...: the rule, the model and the context it was given.
flow-diagram: true adds a Mermaid flowchart LR (inputs, context, analyzers, filters, output, with counts on the
edges) to the block; past 24 nodes it falls back to a stage table. The diagram is written to
.karandash/debug/review-flow.md on every AI run whatever the key says, so a CI job can keep it as an artifact.
Whether your GitLab or GitHub instance renders Mermaid inside a collapsed <details> block has not been checked for
every version, which is why flow-diagram defaults to off; try it on one MR first.
walkthrough: collapsed adds a collapsed changes table (one row per review unit: its files and lines changed) under
the AI changes summary, plus a Mermaid sequenceDiagram when two or more units interact. It needs the mr-summary
analyzer enabled, which makes one call on the shared context prefix and, when the MR description is missing or poor,
also suggests a title and description (the "Suggested Description" block, shown once even if the
generate-description analyzer runs too). All keys inherit through extends:.
Report style
report:
style: standard # quiet | standard (default) | verbose
report.style picks how much every format shows. standard is the compact layout: the markdown summary opens with a
> [!caution] or > [!tip] alert (verdict, counts, new/fixed since the baseline), then one table of findings
(icon | Where | Rule | Finding | How to fix) and the rest in <details>; inline notes lead with rule · message;
the console groups findings by file and ends with one status line; Slack shows at most 5 findings; the html format and
email are a short inline-styled page with a plain-text alternative. quiet also drops explanations, attachments and the metadata list. verbose shows
every detail per finding. A reporters.<format>.style entry overrides it for one format;
validate --style concise|full sets the console (full is verbose). The key inherits through extends:.
Report templates
reporters:
markdown:
template: { file: templates/summary.mustache }
partials:
row: { file: templates/row.mustache }
template: # a custom text format
template: { file: templates/teams.json.mustache }
escape: json # none (default) | md | html | slack | json
maxFindings: 10
markdown, html and slack take a logic-less Mustache template and partials that replace their bundled
standard/quiet layout; {{x}} is escaped for the medium. A broken template logs a warning and the bundled one is
used. karandash format schema prints the data a template sees and karandash format render --template <file> tries
one. See Templates.
Plugins
The plugins: block has the same schema as manifest.yaml. A manifest.yaml next to the config file
or at .karandash/manifest.yaml takes precedence; the config block is used only when there is none.
plugins:
on-missing: fail # warn (default) | fail | ignore: a config entry no loaded module handles
install:
- com.example.jira-integration # id only
- id: com.example.custom-validator
version: "1.0.0"
source: https://example.com/custom-validator.jar
When read from the config file, only install (the declared plugins) and on-missing take effect: a
module referenced under rules:, reporters: or platforms: that is declared but not installed is
reported as such. Registry settings (registry-url, token, auth-header) and directory are read by
the karandash plugin commands from .karandash/manifest.yaml only. Per-plugin config goes under the
plugin's own section (for example rules: { custom-validator: { severity: warning } }).
Environment Variable Interpolation
Karandash supports ${VAR} syntax for environment variable substitution:
platforms:
gitlab:
token: "${GITLAB_TOKEN}"
url: "${GITLAB_URL:-https://gitlab.com}" # With default fallback
Syntax:
- ${VAR} - Reads from environment; when not set it becomes an empty string with warning E0022 and the run
continues (--strict turns the warning into a failure)
- ${VAR:-default} - Reads from environment, uses default if not set
Example:
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
export SLACK_WEBHOOK="https://hooks.slack.com/services/XXX/YYY/ZZZ"
karandash validate
All ${...} placeholders are replaced at runtime.
Config Inheritance with extends
Share configuration across multiple repositories or environments using remote config inheritance.
Basic Inheritance
Base config (https://example.com/karandash-base.yaml):
rules:
title-format:
pattern: "^(feat|fix|chore):.*"
max-length: 120
size-limits:
max-lines: 500
reporters:
console: true
Child config (.karandash/config.yaml):
extends: "https://example.com/karandash-base.yaml"
# Override only what you need
rules:
size-limits:
max-lines: 1000 # Override parent's 500
Result: Child inherits all base rules and overrides max-lines to 1000.
Multi-Level Inheritance
# Level 1: Company-wide standards
extends: "https://company.com/karandash-company.yaml"
rules:
# Level 2: Team-specific overrides
approval:
min-approvals: 3 # Team requires more approvals
Maximum depth: 5 levels (prevents infinite recursion)
Local File Inheritance (Monorepos)
# In packages/frontend/.karandash/config.yaml
extends: "../../../karandash-base.yaml"
rules:
title-format:
pattern: "^(feat|fix)\\(ui\\):.*" # Frontend-specific pattern
File path resolution:
- Relative paths resolve from the directory of the file that declares them (.karandash/), so a package config
reaches the repository root with one more ../ than the package depth: ../../../karandash-base.yaml
- Absolute paths: /repo/karandash-base.yaml
- HTTP(S) URLs: https://example.com/base.yaml (file:// URLs are not supported)
Local files must sit under the project root: the git top-level (found by walking up from the working directory
and from the root config for a .git entry) or the directory holding the discovered .karandash/, whichever is
higher. A config discovered from a subdirectory and a monorepo package extending a base at the repository root are
inside it; a path outside it fails with E0009 naming the root. A config fetched over HTTP(S) can never read a
local file.
Inheritance Merge Behavior
Merge strategy: Deep merge with child priority
Example:
Base config:
rules:
approval:
min-approvals: 2
required-approvers: ["tech-lead"]
Child config:
extends: "base.yaml"
rules:
approval:
min-approvals: 3 # Overrides base
# required-approvers inherited from base
Result:
rules:
approval:
min-approvals: 3 # From child
required-approvers: ["tech-lead"] # From base
Lists are replaced, not merged:
Base:
rules:
jira-ticket:
project-keys: ["PROJ", "TASK"]
Child:
extends: "base.yaml"
rules:
jira-ticket:
project-keys: ["NEWPROJ"] # Replaces, doesn't append
Result: project-keys: ["NEWPROJ"] (not ["PROJ", "TASK", "NEWPROJ"])
Error Handling
Circular dependency:
# config-a.yaml
extends: "config-b.yaml"
# config-b.yaml
extends: "config-a.yaml" # ERROR: Circular reference
Error: E0010: Circular config inheritance detected
Max depth exceeded:
# config-level-6.yaml
extends: "config-level-5.yaml" # ERROR: Max depth is 5
Error: E0011: Config inheritance depth exceeded (max: 5)
Fetch failure:
extends: "https://example.com/missing.yaml" # ERROR: 404 Not Found
Error: E0009: Remote config fetch failed: 404
Migration from Kotlin DSL
Field Name Mapping
YAML uses kebab-case, Kotlin DSL uses camelCase:
| YAML | Kotlin DSL |
|---|---|
title-format |
titleFormat |
commit-messages |
commitMessages |
jira-ticket |
jiraTicket |
branch-naming |
branchNaming |
file-changes |
fileChanges |
cicd-status |
cicdStatus |
size-limits |
sizeLimits |
min-length |
minLength |
max-length |
maxLength |
require-ticket |
requireTicket |
project-keys |
projectKeys |
block-draft |
blockDraft |
wip-patterns |
wipPatterns |
azure-devops |
azureDevOps |
aws-codecommit |
awsCodeCommit |
base-url |
baseUrl |
allowed-patterns |
allowedPatterns |
require-source-match |
requireSourceMatch |
require-target-match |
requireTargetMatch |
required-labels |
requiredLabels |
forbidden-labels |
forbiddenLabels |
conditional-labels |
conditionalLabels |
required-reviewers |
requiredReviewers |
required-teams |
requiredTeams |
excluded-reviewers |
excludedReviewers |
require-passed |
requirePassed |
required-jobs |
requiredJobs |
block-on-conflicts |
blockOnConflicts |
scan-for-secrets |
scanForSecrets |
block-on-draft |
blockOnDraft |
no-changes-since-approval |
noChangesSinceApproval |
require-owner-approval |
requireOwnerApproval |
Conversion Example
Kotlin DSL (.karandash/config.kts):
rules {
titleFormat {
pattern = "^feat:.*"
maxLength = 120
}
sizeLimits {
maxLines = 500
}
}
reporters {
console = true
}
Equivalent YAML (.karandash/config.yaml):
rules:
title-format:
pattern: "^feat:.*"
max-length: 120
size-limits:
max-lines: 500
reporters:
console: true
Environment Variables
Kotlin DSL:
platforms {
gitlab {
token = env.GITLAB_TOKEN
}
}
YAML:
platforms:
gitlab:
token: "${GITLAB_TOKEN}"
Lists
Kotlin DSL:
jiraTicket {
projectKeys = listOf("PROJ", "TASK")
}
YAML:
jira-ticket:
project-keys:
- "PROJ"
- "TASK"
Common Configurations
Minimal (Quick Start)
rules:
title-format:
pattern: "^(feat|fix|docs):.*"
draft:
block-draft: fail
reporters:
console: true
Standard (Most Teams)
rules:
title-format:
pattern: "^(feat|fix|chore|docs):.*"
min-length: 10
max-length: 120
size-limits:
max-lines: 500
max-files: 30
draft:
block-draft: fail
approval:
min-approvals: 2
conflict:
block-on-conflicts: fail
reporters:
console: true
Strict (Enterprise)
extends: "https://company.com/base.yaml"
rules:
title-format:
pattern: "^\\[JIRA-\\d+\\] (feat|fix|chore):.*"
require-ticket: true
jira-ticket:
project-keys: ["PROJ", "TASK"]
validate-status: ["In Progress", "In Review"]
approval:
min-approvals: 3
required-approvers: ["tech-lead", "architect"]
no-changes-since-approval: true
security:
scan-for-secrets: true
secret-patterns:
- "(?i)(api[_-]?key|apikey)\\s*=\\s*['\"][^'\"]+['\"]"
reporters:
console: true
markdown: true
slack:
webhook: "${SLACK_WEBHOOK}"
channel: "#code-reviews"
Multi-Repo (Monorepo with Inheritance)
Root config (karandash-base.yaml):
rules:
title-format:
pattern: "^(feat|fix|chore):.*"
max-length: 120
draft:
block-draft: fail
reporters:
console: true
Frontend config (packages/frontend/.karandash/config.yaml):
extends: "../../../karandash-base.yaml"
rules:
title-format:
pattern: "^(feat|fix)\\(ui\\):.*" # UI-specific
Backend config (packages/backend/.karandash/config.yaml):
extends: "../../../karandash-base.yaml"
rules:
approval:
min-approvals: 3 # Backend needs more approvals
Validation and Error Handling
Invalid YAML Syntax
Error: E0006: Invalid YAML syntax
rules:
title-format:
pattern: "unclosed string
Fix: Close the string properly:
rules:
title-format:
pattern: "closed string"
Unknown Configuration Key
Error: E0007: Unknown YAML config key: 'titel-format'
Suggestion: Did you mean 'title-format'?
rules:
titel-format: # Typo
pattern: ".*"
Fix:
rules:
title-format:
pattern: ".*"
Invalid Type
Error: E0008: Invalid config value type for 'max-length': expected number, got string
rules:
title-format:
max-length: "120" # Should be number, not string
Fix:
rules:
title-format:
max-length: 120
Best Practices
-
Use environment variables for secrets - Never commit tokens:
yaml platforms: gitlab: token: "${GITLAB_TOKEN}" # Good # token: "glpat-hardcoded" # BAD -
Start with
extendsfor consistency - Share base config across repos:yaml extends: "https://company.com/karandash-base.yaml" -
Comment your overrides - Explain why you deviate from defaults:
yaml rules: size-limits: max-lines: 1000 # Legacy codebase, can't refactor yet -
Use relative paths in monorepos - Enables moving directories:
yaml extends: "../../base.yaml" # Good # extends: "/absolute/path/base.yaml" # Bad -
Pin remote configs with versioning - Avoid breaking changes:
yaml extends: "https://company.com/base-v1.2.yaml" # Good # extends: "https://company.com/base-latest.yaml" # Bad -
Generate YAML from init command - Don't write from scratch:
bash karandash init --format yaml(yamlis the default, so plainkarandash initalso produces YAML.)
FAQ
Q: Can I mix YAML and Kotlin DSL?
A: No. Karandash uses whichever config file it finds first (.karandash/config.kts takes priority over .karandash/config.yaml).
Q: Does YAML support all features of Kotlin DSL?
A: Yes. Both formats map to the same Config model and have identical capabilities.
Q: How do I validate my YAML config?
A: Run karandash validate --config .karandash/config.yaml. Parsing errors will be reported immediately.
Q: Can I use YAML in extends and Kotlin DSL for local config?
A: No. The parent config format must match the child config format (both YAML or both Kotlin DSL).
Q: Does YAML config work in Docker?
A: Yes. Mount your config file or use environment variables:
bash
docker run -v .karandash/config.yaml:/app/.karandash/config.yaml rinekri/karandash:latest karandash validate
Related Documentation
- Zero-Config Mode - Validation without config files
- Config Inheritance Deep Dive - Advanced
extendsusage - Kotlin DSL Reference - Alternative config format
- CLI Commands - Command-line options