Configuration

Prelint works without any configuration. Install the GitHub App, and every PR gets reviewed. Add a prelint.json to your repository root when you want to exclude files, add custom rules, decide when reviews run, or control what context the review engine sees.

Quick start

Create a prelint.json file in your repository root:

{
  "version": 1,
  "exclude_authors": ["dependabot[bot]", "renovate[bot]"]
}

That's it. Prelint indexes markdown files in your repo automatically and reviews every PR.

Configuration priority

Settings are merged from multiple sources. Higher-priority sources override lower ones:

1. Built-in defaults: sensible starting configuration.
2. Organization settings: set in the Prelint dashboard for all repos.
3. Project settings: scoped to a project in the dashboard.
4. Repository settings: set in the dashboard for a specific repo.
5. prelint.json: highest priority. Lives in the repo, versioned with your code.

Full schema reference

Review triggers

Two settings and one comment tag decide when a review starts. Set the settings in the dashboard at organization, project, or repository scope.

Author allowlist

include_authors lists PR authors. Empty list: every author gets reviews. Add names: only those authors do. Case does not matter.

• Lists add up across scopes. A repository can extend the organization list, never shrink it.
• Excludes win. An author on both lists is skipped. Built-in bot exclusions stay active.
• A skipped PR still gets a neutral check run, so a required Prelint check can pass. The check names the scope that set the list.

Tag a PR with @prelint

Comment @prelint on any pull request to start a review. That is the whole command: no verb, no arguments, any casing.

• You need write access to the repository. You do not need a Prelint account.
• Works in auto mode too, not just tag_only. Example: review a draft PR before it is ready.
• Mentions inside code blocks, quotes, and links do not count. Any other mention counts, even mid-sentence.
• Each commit is reviewed once. Push new commits, then tag again.
• When Prelint cannot run the review, it replies to your comment with the reason.

Trigger mode

trigger_mode switches automatic reviews on or off. auto (default): every PR open or push starts a review. tag_only: nothing starts by itself; use the @prelint tag or the Run review button.

Ignore patterns

Use glob syntax to exclude files from reviews. Patterns are matched against the file path relative to the repository root.

{
  "ignore_patterns": [
    "docs/**",
    "**/*.test.ts",
    "migrations/**",
    "*.generated.ts",
    "!docs/api/**"
  ]
}

Built-in exclusions (always ignored):

• *.lock, *-lock.*: lock files
• vendor/**, node_modules/**: vendored dependencies
• *.min.js, *.min.css: minified assets
• *.png, *.jpg, *.gif, *.svg, *.ico: images
• *.woff, *.woff2, *.ttf, *.eot: fonts

Prefix a pattern with ! to negate it (force-include a file that would otherwise be ignored).

Rules

Custom rules let you enforce project-specific requirements beyond what specs cover. Each rule has a name and a description that the review engine uses.

{
  "rules": [
    {
      "name": "No direct database queries in handlers",
      "description": "All database access must go through the repository layer. Handler functions should not import or use database clients directly."
    },
    {
      "name": "Feature flags for new endpoints",
      "description": "New API endpoints must be wrapped in a feature flag. Use the featureFlags.isEnabled() check before executing endpoint logic."
    }
  ]
}

Rules are included in the review context alongside specs. The review engine evaluates every diff change against all active rules.

Context files

Context files provide additional information to the review engine without being formal specs. Use them for:

• API documentation that the code should match
• Database schemas that inform business logic
• Design system guidelines for frontend code
• Third-party integration docs that constrain implementation

{
  "context_files": [
    "docs/api-reference.md",
    "docs/database-schema.md",
    "ARCHITECTURE.md"
  ]
}

Context files differ from specs: specs define what should be built, context files provide background information that helps the review engine understand your codebase.

Outgoing webhooks

Subscribe to review lifecycle events and route them to Slack, your CI pipeline, or any HTTP endpoint. Configure webhooks in the Prelint dashboard under Settings → Webhooks.

Webhook events include:

• review.completed: fired when a review finishes, with all findings.
• review.failed: fired when a review fails to complete.
• review.skipped: fired when a review is skipped (draft PR, excluded author, etc.).

Webhooks deliver asynchronously with automatic retries and exponential backoff. Transient failures won't lose your events.

Complete example

{
  "version": 1,
  "exclude_authors": [
    "dependabot[bot]",
    "renovate[bot]"
  ],
  "include_authors": [
    "alice",
    "bob"
  ],
  "trigger_mode": "auto",
  "ignore_patterns": [
    "docs/**",
    "**/*.test.ts",
    "**/*.spec.ts",
    "migrations/**"
  ],
  "rules": [
    {
      "name": "Repository pattern",
      "description": "All database access must use the repository pattern. No direct ORM calls in service or handler files."
    }
  ],
  "context_files": [
    "ARCHITECTURE.md",
    "docs/api-reference.md"
  ],
  "output": {
    "comments": true,
    "check_run": true
  }
}