.gitcaptain.yml Reference

Platform & Reviews CLI & Local Tool

Configuration & Rules Enterprise & VPC

4 min read

Fine-tune inspection depth, token budgets, excluded file paths, and auto-review triggers.

Fine-tune inspection depth, token budgets, excluded file paths, and auto-review triggers.

Configuration File Location

Commit a .gitcaptain.yml or .gitcaptain.json file to the root of your default repository branch:

text

your-repo/
├── .gitcaptain.yml
├── package.json
└── src/

Complete .gitcaptain.yml Example

yaml

version: "1.0"

# Pull request automation controls
review:
  auto_review:
    drafts: false
    branches:
      include: ["main", "develop", "release/*"]
      exclude: ["feature/wip-*"]
  summaries:
    enabled: true
    complexity_radar: true
  inline_comments:
    max_comments: 8
    severity_threshold: "warning" # info | warning | critical

# Tree-sitter AST parser configurations
ast:
  languages: ["typescript", "javascript", "python", "go"]
  max_file_size_kb: 500
  ignore_patterns:
    - "**/*.min.js"
    - "**/generated/**"
    - "**/vendor/**"
    - "package-lock.json"
    - "pnpm-lock.yaml"

# Inference provider preference
providers:
  primary: "google"
  model: "gemini-2.5-flash"
  fallback: "groq"
  fallback_model: "llama-3.3-70b-versatile"

Schema Fields & Parameter Table

Parameter	Type	Default	Description
`review.auto_review.drafts`	`boolean`	`false`	Set `true` to trigger reviews on draft pull requests.
`review.inline_comments.max_comments`	`number`	`8`	Cap on inline comments per review to avoid alert fatigue.
`review.inline_comments.severity_threshold`	`string`	`"warning"`	Minimum severity (`info`, `warning`, `critical`) required for inline comment.
`ast.ignore_patterns`	`string[]`	`[]`	Glob patterns excluded from AST parsing and LLM prompts.
`providers.fallback`	`string`	`"groq"`	Backup provider if primary encounters rate limit.

3 min read

Custom AST Pattern Rules

Enforce organizational coding standards and architectural invariants with syntax-tree matching.

Enforce organizational coding standards and architectural invariants with syntax-tree matching.

Why AST Pattern Matching?

Traditional regex linters cannot differentiate between actual code, string literals, and commented-out snippets.

GitCaptain uses syntax-tree node queries to match structural patterns regardless of indentation or formatting.

Rule Definition Syntax

Define custom rules in .gitcaptain.yml:

yaml

rules:
  - id: no-raw-fetch-in-client
    severity: critical
    language: typescript
    pattern: |
      call_expression
        function: (identifier) @fn (#eq? @fn "fetch")
    message: "Direct 'fetch()' calls are prohibited in client components. Use the centralized 'apiClient' wrapper instead."
    paths:
      include: ["frontend/src/components/**"]

Common Architectural Rule Examples

1. Prohibit Raw SQL Strings

yaml

rules:
  - id: no-raw-sql-concatenation
    severity: critical
    language: typescript
    pattern: |
      binary_expression
        left: (string) @str (#match? @str "SELECT|INSERT|UPDATE|DELETE")
        operator: "+"
    message: "Potential SQL injection detected. Use parameterized queries via ORM or prepared statements."

2. Enforce Proper Error Logging

yaml

rules:
  - id: no-empty-catch-blocks
    severity: warning
    language: javascript
    pattern: |
      catch_clause
        body: (statement_block) @block (#eq? @block "{}")
    message: "Empty catch blocks swallow exceptions silently. Log the error or re-throw."

3 min read

Path-Based Custom Review Instructions

Tailor review focus, strictness, and instructions according to repository subdirectories and glob patterns.

Tailor review focus, strictness, and instructions according to repository subdirectories and glob patterns.

Path Instructions Concept

Not all files in a repository require the same review criteria:

API Endpoints require strict authentication, authorization, and input validation checks.

Frontend Components need scrutiny around accessibility, hydration mismatches, and layout shift.

Database Migrations require checks against destructive table locks or unbounded column additions.

Path instructions allow you to attach natural-language prompts to specific file globs.

Configuration Format

yaml

path_instructions:
  - path: "src/api/**"
    instructions: |
      Pay special attention to:
      1. Every route must validate user session scopes.
      2. Ensure query parameters are sanitized with Zod schemas.
      3. Verify database transactions commit or roll back gracefully.

  - path: "src/components/**"
    instructions: |
      1. Verify all interactive elements have accessible aria-labels.
      2. Ensure images have explicit width and height to prevent CLS.
      3. Flag any unmemoized high-frequency callbacks.

  - path: "prisma/migrations/**"
    instructions: |
      1. Warn if an ALTER TABLE statement adds a NOT NULL column without a default value.
      2. Flag any column rename that would break zero-downtime rolling deploys.