Overview

Policies are a way to extend Korbit's out-of-the-box comprehensive reviews, by allowing you to specify rules that are specific to you and your team's way of doing things. Policies are not required to get started with Korbit, but they are a powerful way to enforce your team's standards.

Unlike linters, which handle syntax and formatting, Korbit Policies˝ can enforce higher-level expectations:

• Turn your team's best practices into code - Capture team guidelines, naming conventions, and workflow expectations in a structured, version-controlled file.

• Enforce standards that linters can't - Go beyond formatting — enforce things like API usage, service boundaries, and process rules at the PR level.

• Accelerate onboarding and reduce review friction - Help new developers follow team conventions from day one, and reduce repetitive back-and-forth in code reviews.

• Continuously improve your codebase - Track which rules are effective, refine unclear ones, and evolve your standards over time with real developer feedback.

Click here to view examples of policies in action: Examples

Key Configuration Options

The configuration file is written in YAML format and should be placed in the root of your repository.

# yaml-language-server: $schema=https://docs.korbit.ai/configuration/korbit-policies-schema.v0.1.json
version: "0.1" # Schema version. Required to ensure compatibility with policy validator
topics:
    - name: "Topic A" # Example topic showing the structure of a policy
      paths:
        - '**/*' # Glob pattern matching all files in the project
      policies:
        - title: Policy A1 Title # First policy in Topic A
          description: |
            Describe what this rule enforces in a clear and specific way.
          impact: |
            Describe why this rule is important for the code base.
          code_examples:
            - non_compliant: |
                  # Bad code example for A1
                  something_wrong()
              compliant: |
                  # Good code example for A1
                  something_right()

Schema Validator

How do policy issues show up in reviews?

When Korbit detects a policy violation, it will be included alongside the out of the box Korbit review comments with a category of Policy.

You are also able to filter for policy violations in the Korbit Console's issues tab.

Tips for Writing Your First Policy

• Start with friction: What do you or your reviewers correct most often?
• Think like a teammate: Would someone new to the project benefit from this being enforced?
• Use real code examples: Show what’s allowed and what’s not — Korbit will use them for training and suggestions.
• Be opinionated: Policies work best when they reflect your internal practices.

Testing and Iterating on Policies

1. Create a .korbit-policies.yaml file in a branch, create a pull request, and push code that violates the policy to verify that the policy is working as expected. To trigger a new review you can use the /korbit-full-review command.
2. Once you have verified that the policy is working as expected, remove the code that violates the policy and merge the pull request into your main branch.
3. Every time Korbit reviews your code, it will check for policy violations and report them in the PR comments.

Examples

# yaml-language-server: $schema=https://docs.korbit.ai/configuration/korbit-policies-schema.v0.1.json
version: "0.1" # Schema version. Required to ensure compatibility with policy validator
topics:
  - name: "API Service Usage"
    paths:
      - '**/*'
    policies:
      - title: Deprecated FetchWrapper usage
        description: |
          All API calls must be made through ApiService
          instead of directly using the legacy FetchWrapper.
        impact: |
          Using the service classes instead of direct FetchWrapper calls is crucial
          for maintaining a clean and consistent codebase. When we centralize our
          API logic in these service classes, we make it much easier to update how
          we handle authentication, error cases, or even switch out the underlying
          implementation.
        code_examples:
          - non_compliant: |
              const response = await fetchWrapper<SomeType>({
                path: '/api/some-endpoint',
                options: { method: 'GET' }
              });
            compliant: |
              const response = await apiService.someEndpoint.get();