Skip to content

Zero-Config Mode

Zero-config mode enables you to start validating merge requests in under 5 minutes without creating any configuration files. Karandash will use sensible default rules that catch common issues while you decide on your team's standards.

What is Zero-Config Mode?

Zero-config mode activates automatically when you run karandash validate in a repository without a .karandash/config.kts or .karandash/config.yaml file. Instead of failing with "config not found", Karandash applies a curated set of default validation rules.

Quick Start

# 1. Set authentication (one-time setup)
export GITLAB_TOKEN="your-token-here"

# 2. Run validation - that's it!
karandash validate

No config file needed. No initialization step. Just validate.

Default Rules

Zero-config mode applies these rules with the severities indicated:

Rule Default Setting Severity Description
Title Format Conventional commits pattern ERROR Requires feat:, fix:, chore:, etc. prefix
Title Length Min: 10 chars (no max) ERROR Minimum length enforced; maximum not enforced
Size Limits Max 500 lines changed ERROR Flags large PRs (blocks merge)
Draft Block Blocks draft MRs ERROR Prevents accidental merge of WIP changes
Max Commits 20 commits per MR ERROR Enforces commit count limit (blocks merge)

Note on description validation: zero-config does not check the MR description. Description checks come from the opt-in descriptionFormat rule (required sections), which needs a config file.

Default Title Pattern

^(feat|fix|chore|docs|test|refactor|style|perf):.*

Accepts conventional commit formats: - feat: add user authentication - fix: handle null response - chore: update dependencies

Environment Variable Authentication

Zero-config mode reads authentication tokens from environment variables. No config file required.

GitLab

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
export GITLAB_URL="https://gitlab.com"  # Optional, defaults to gitlab.com

Token Permissions: api or read_api scope

CI/CD Auto-Detection: In GitLab CI, uses CI_JOB_TOKEN automatically if GITLAB_TOKEN is not set.

GitHub

export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
export GITHUB_API_URL="https://api.github.com"  # Optional, for GHE

Token Permissions: repo scope (or public_repo for public repos only)

GitHub Actions: Uses GITHUB_TOKEN from workflow context automatically.

Bitbucket

export BITBUCKET_TOKEN="your-app-password"
export BITBUCKET_USERNAME="your-username"

Token Type: App password with pullrequest:read permission

Azure DevOps

export AZURE_DEVOPS_TOKEN="your-pat-token"
export AZURE_DEVOPS_ORG="your-organization"

Token Permissions: Code (Read) scope

Gerrit

export GERRIT_USERNAME="your-gerrit-username"
export GERRIT_TOKEN="your-http-password"
export GERRIT_URL="https://gerrit.example.com"

Token Type: HTTP password from user settings

Gitea

export GITEA_TOKEN="your-access-token"
export GITEA_URL="https://gitea.example.com"

Token Permissions: read:repository scope

AWS CodeCommit

export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
export AWS_REGION="us-west-2"

IAM Permissions: codecommit:GetPullRequest and related read permissions

Example Output

[INFO] No configuration file found
[INFO] Using zero-config mode with default rules
[INFO] Set GITLAB_TOKEN to authenticate with GitLab

Validating MR #123: feat: add user authentication

✓ Title format matches conventional commits
✓ Title length: 32 characters (min 10)
✗ Size: 650 lines changed (max: 500)
✓ Not a draft MR
✓ Commits: 5 (max: 20)

✗ 1 error found

Validation FAILED (errors block merge)

Note: The size limit and draft blocking rules enforce strict limits with ERROR severity. This differs from the previous behavior which used WARNING severity. Adjust defaults via custom configuration if needed.

When to Use Zero-Config vs Custom Config

Use Zero-Config When:

  • Testing Karandash - Trying it out before committing to configuration
  • Starting a new project - Don't have team standards defined yet
  • Small teams - Default rules are good enough
  • Quick validation - Need to validate a PR URL locally without setup
  • CI experimentation - Testing Karandash in CI without config overhead

Use Custom Config When:

  • Established standards - Your team has specific conventions
  • Stricter enforcement - Need ERROR severity on size limits
  • Custom patterns - Non-conventional commit formats
  • Advanced rules - Need JIRA ticket validation, CODEOWNERS, etc.
  • Multiple repos - Want to share config via extends inheritance
  • Platform-specific - Different rules for GitHub vs GitLab

Upgrading from Zero-Config

When you're ready to customize, generate a config file with karandash init:

# Generate YAML config (the default format)
karandash init

# Or pick a different format: yaml, json, kts
karandash init --format kts
karandash init --format json

# Or start from a named profile
karandash init --profile conventional-commits
karandash init --profile github-flow

# Write to a specific path
karandash init --output .karandash/config.yaml
Option Alias Values Default
--format -f yaml, json, kts yaml
--profile -- minimal, conventional-commits, github-flow, gitflow, trunk-based, semantic-versioning, security-conscious none (a minimal config is generated)
--output -o any path the default path for the chosen format

Without --profile, init writes the same minimal ruleset that zero-config applies, so the generated file is a direct starting point for customization. init never overwrites an existing config file - it reports the existing path and exits.

Zero-Config with Local PR Testing

Combine zero-config with the --pr flag for instant validation:

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

# No config file needed
karandash validate --pr https://gitlab.com/myorg/myrepo/-/merge_requests/123

Perfect for: - Testing PRs from external repositories - Validating before creating your own PR - Quick checks without cloning the repository

Zero-Config in CI/CD

GitLab CI

karandash-validate:
  stage: test
  image: rinekri/karandash:latest
  rules:
    - if: $CI_MERGE_REQUEST_IID
  script:
    - karandash validate
  variables:
    GITLAB_TOKEN: $CI_JOB_TOKEN  # Auto-provided by GitLab

GitHub Actions

name: Karandash Validation
on: pull_request

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate PR
        uses: docker://rinekri/karandash:latest
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          args: validate

Both examples work without a config file in your repository.

Overriding Defaults

Create a config file to override any default rule:

Kotlin DSL (.karandash/config.kts):

rules {
    titleFormat {
        // Override only the pattern, keep other defaults
        pattern = "^\\[JIRA-\\d+\\] .+"
    }
}

YAML (.karandash/config.yaml):

rules:
  title-format:
    # Override only the pattern, keep other defaults
    pattern: "^\\[JIRA-\\d+\\] .+"

Even with one rule override, you still benefit from other zero-config defaults.

Limitations

Zero-config mode does not support:

  • Customizing severity levels - Rules use fixed severities (most are ERROR, blocking merges)
  • Description validation - Not part of the zero-config defaults; configure descriptionFormat in a config file
  • Advanced validators - JIRA ticket validation, CODEOWNERS, file-specific rules
  • Custom reporters - Only console output (no Slack, SARIF, etc.)
  • Plugin loading - Custom plugins require explicit configuration
  • Config inheritance - Cannot extend remote configs without a base config file

For these features, you need a configuration file (Kotlin DSL or YAML).

Severity Behavior in Zero-Config

Most zero-config rules use ERROR severity, which blocks merges: - Title format violations - Title minimum length violations - Size limit violations (maxLines, maxCommits) - Draft detection

To use non-blocking (WARNING) rules, create a custom configuration with .karandash/config.kts or .karandash/config.yaml.

FAQ

Q: How do I know if zero-config mode is active?

A: Karandash prints [INFO] Using zero-config mode with default rules when no config file is found.

Q: Can I customize zero-config defaults?

A: No. Zero-config provides fixed defaults. To customize, create a config file with karandash init.

Q: Do zero-config rules change between versions?

A: Defaults may improve in major versions. Pin your Docker image tag (rinekri/karandash:v1.0.1) for stability.

Q: Can I use zero-config with custom plugins?

A: No. Plugins require a config file to specify which plugins to load and their settings.

Q: Does zero-config work in CI without environment variables?

A: In GitLab CI, CI_JOB_TOKEN is auto-detected. In GitHub Actions, GITHUB_TOKEN must be passed explicitly.

Q: Why do zero-config rules block my PRs with ERROR severity?

A: Zero-config enforces strict rules (ERROR severity) to keep quality up. If you need more lenient rules (WARNING severity that don't block merges), create a custom configuration file with karandash init.

Q: Does zero-config check the MR description?

A: No. Add a config file with the descriptionFormat rule to require description sections.