Skip to main content
cubic.yaml lives in the root of your repository and becomes the source of truth for AI review behavior, ignore patterns, PR descriptions, and custom rules. Commit the file, open a PR, and cubic automatically applies those settings to every future review.
Public Beta: Repository-level cubic.yaml configuration is now available in public beta. We’re actively improving the feature based on feedback, so expect some changes as we refine the experience.

​
Configuration hierarchy

cubic.yaml configuration takes priority over the settings in the cubic UI whenever it parses correctly. If cubic.yaml is missing or invalid, cubic uses your existing UI settings. Partial YAML is supported. Any field you set in cubic.yaml overrides the UI. Anything you leave out keeps the UI value. Validation errors do not block reviews. If the YAML has an issue, cubic keeps using the UI settings and shows the exact error on the AI review settings page so you can fix it on your next commit.

​
Exporting current UI settings

If you’ve already configured AI review settings in the UI, you can export them as a cubic.yaml file instead of creating one manually.
  1. Go to the AI review settings page and select a repository.
  2. In the tabs area at the top, you’ll see two buttons:
    • Copy button: Copies the YAML configuration to your clipboard
    • Download button: Downloads a cubic.yaml file with your current settings
  3. Paste the copied content or use the downloaded file as a starting point for your repository configuration.
The exported YAML includes all your current UI settings. You can then commit this file to your repository root and customize it as needed. Export Yaml Buttons Pn

​
Template cubic.yaml

Copy this template into the root of your repository to get started, then delete any sections you don’t need to customize. 
# yaml-language-server: $schema=https://cubic.dev/schema/cubic-repository-config.schema.json

version: 1

# Review settings control AI review behavior.
reviews:
  enabled: true
  sensitivity: medium
  incremental_commits: true
  custom_instructions: |
    Outline any project-specific guidance you want included in reviews.

  # Optional ignore filters; cubic skips reviews when these match.
  ignore:
    files:
      - path/to/generated/**
    head_branches:
      - wip/*
    pr_labels:
      - skip-review

  # Optional YAML-defined custom rules.
  custom_rules:
    - name: Example rule
      description: Describe what this rule should flag.
      # include/exclude lists are optional—delete them to apply everywhere.
      include:
        - src/**
      exclude:
        - src/**/*.test.*

pr_descriptions:
  generate: true
  instructions: |
    Add reminders or release notes here.

# Issues block (delete if you don't use Fix with cubic buttons).
issues:
  fix_with_cubic_buttons: true
  1. Create the file at the repo root.
  2. Commit it to a branch and open a PR.
  3. Watch the AI review settings page or PR timeline for validation errors or warnings.
See the AI review settings page for the UI view of these values.

​
IDE validation

Editors such as VS Code, Cursor, and JetBrains detect the # yaml-language-server: $schema=… directive at the top of cubic.yaml. Keep that line (or add it yourself) and the editor downloads https://cubic.dev/schema/cubic-repository-config.schema.json to validate the file structure and surface inline errors before you commit.

​
Configuration reference

KeyRequiredPurpose
versionYesSchema version. Must be 1.
reviewsNoMirrors AI review settings and lets you define custom rules.
pr_descriptionsNoControls AI-authored PR summaries and optional instructions.
issuesNoEnables the “Fix with cubic” issue buttons.
If you add a top-level key cubic doesn’t recognize yet, the value is ignored and an unknown_top_level_key warning appears on the AI review settings page so you know it had no effect.

​
Reviews section

​
Core options

FieldDescription
enabledMaster toggle for AI reviews on the repository.
sensitivitylow, medium, or high—controls how picky the AI is about surfacing issues.
incremental_commitstrue re-runs reviews on every push; false limits reviews to the first commit.
custom_instructionsFree-form guidance for the reviewer. Whitespace is trimmed; empty strings clear the value.

​
Ignore filters

Ignore filters control when cubic skips running reviews. They map directly to the “Ignore patterns” controls in the AI review settings UI. All lists accept glob strings, and duplicates/blank entries are dropped automatically.
YAML pathEffect
reviews.ignore.filesSkip matching files entirely (same syntax as .gitignore).
reviews.ignore.head_branchesIgnore PRs based on their source branch.
reviews.ignore.base_branchesIgnore PRs targeting specific base branches.
reviews.ignore.pr_labelsIgnore PRs with one of these labels.
reviews.ignore.pr_titlesIgnore PRs whose titles match the provided wildcard patterns.

​
Custom rules

  • Each rule needs a name, description, and optional include/exclude glob lists.
  • Order matters. When you exceed the installation’s rule limit, only the first N rules take effect.
  • Identical patterns are deduplicated. If an exclude matches an include, the exclude wins.
  • Rules defined in YAML appear in the dashboard as read-only “Managed by cubic.yaml” entries so teammates can still see them. Learn more about how rules behave in the UI on the Custom rules page.

​
PR descriptions

FieldDescription
generateToggle AI-authored PR descriptions.
instructionsExtra guidance for the summary. Only applied when generate is true; otherwise it is ignored with a warning.
Some installations disable PR descriptions globally for compliance reasons. If that applies to you, the UI will show a warning even if the YAML enables the feature.

​
Issues

FieldDescription
fix_with_cubic_buttonsEnable or disable AI-generated “Fix with cubic” calls-to-action inside the issue UI.