Configure with cubic.yaml

Public Beta: cubic.yaml configuration is now available in public beta.

Repository configuration

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 agents. Commit the file, open a PR, and cubic automatically applies those settings to every future review.

Organization configuration

You can also manage cubic settings for your entire organization from a single repository. Create a repository named cubic-config in your organization and add a cubic.yaml file to the root directory. cubic automatically applies these settings to any repository that doesn’t have its own configuration. Organization configuration uses the same schema as repository configuration, including auto-approve settings such as reviews.auto_approve_behavior, reviews.auto_approve, and reviews.auto_approve_custom_prompt. Organization configuration is read from the default branch of cubic-config. Changes are picked up automatically when you push to the default branch, and cubic invalidates its cache so the next review on any repository in the org uses the updated settings.

You must add the cubic-config repository to your cubic installation. cubic needs access to read the configuration file.

Individual repositories can still override organization settings by adding their own cubic.yaml file. The cubic-config repository itself is always treated as organization configuration. Its cubic.yaml is never interpreted as a repo-level override.

Configuration hierarchy

cubic checks for configuration in this priority order:

Priority	Source	Description
1 (Highest)	Repository `cubic.yaml`	Settings defined in the repository root
2	Organization `cubic.yaml`	Settings from `{org}/cubic-config` repository
3	UI settings	Per-repository settings configured in the cubic dashboard
4 (Lowest)	Defaults	Built-in cubic defaults

UI settings are stored per-repository. The “All repositories” option in the dashboard applies changes to all existing repositories at once, but new repositories start with built-in defaults. Use organization cubic.yaml to ensure consistent defaults across all repositories, including new ones.

Merging behavior

Partial YAML is supported at every level. Any field you set overrides lower-priority sources. Anything you leave out falls through to the next level. When both repository and organization YAML exist, cubic merges them:

The organization config acts as a base
Repository settings override organization settings field-by-field
Settings not defined in the repository YAML inherit from organization YAML
Custom agents are additive: repository agents come first, then organization agents fill remaining slots

This allows you to define organization-wide defaults in the organization config while letting repositories customize specific settings.

To opt out of custom agents defined in organization config entirely, set custom_rules: [] in your repository config. This explicitly clears inherited agents rather than adding to them.

Example: Merging organization and repository config

Organization config (cubic-config/cubic.yaml):

version: 1
reviews:
  enabled: true
  sensitivity: high
  custom_instructions: "Outline any project-specific guidance you want included in reviews."
  custom_rules:
    - name: No console logs in production
      description: Ensure that console.log statements are removed before merging. These should not be present in production code to prevent leaking sensitive information and to improve performance.

Repository config (my-repo/cubic.yaml):

version: 1
reviews:
  sensitivity: low  # Override org's "high"
  custom_rules:
    - name: API validation
      description: Check API contracts

Effective config (what cubic uses):

enabled: true — inherited from organization
sensitivity: low — overridden by repository
custom_instructions: "Outline any project-specific guidance..." — inherited from organization
Custom agents: “API validation” (from repo), then “No console logs” (from organization)

Error handling

Validation errors do not block reviews. If the YAML has an issue, cubic falls back to UI settings and shows the exact error on the AI review settings page so you can fix it on your next commit. Note that an invalid repository cubic.yaml falls back to UI settings, not to organization configuration—this keeps failure modes predictable.

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.

Go to the AI review settings page and select a repository.
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
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.

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
  check_drafts: false
  architecture_diagrams: false
  external_contributors_require_manual_review: false
  resolve_threads_when_addressed: true
  auto_approve_behavior: disabled
  auto_approve: disabled
  auto_approve_custom_prompt: |
    Approve only documentation, test, and configuration changes.
  auto_approve_rules:
    exclude:
      - '**/migrations/**'
      - infra/**
  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 agents.
  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 PR comment fixes or "Fix with cubic" buttons).
issues:
  fix_with_cubic_buttons: true
  pr_comment_fixes: true
  fix_commits_to_pr: true

Create the file at the repo root.
Commit it to a branch and open a PR.
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

Key	Required	Purpose
`version`	Yes	Schema version. Must be `1`.
`reviews`	No	Mirrors AI review settings and lets you define custom agents.
`pr_descriptions`	No	Controls AI-authored PR summaries and optional instructions.
`issues`	No	Controls “Fix with cubic” buttons and PR comment-requested fixes.

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

Field	Description
`enabled`	Master toggle for AI reviews on the repository.
`sensitivity`	`low`, `medium`, or `high`—controls how picky the AI is about surfacing issues.
`incremental_commits`	`true` reviews new commits pushed to open PRs (only new issues are posted); `false` reviews only when the PR is first opened. Default: `true`.
`check_drafts`	`true` reviews draft PRs immediately when opened; `false` skips them. Default: `false`.
`architecture_diagrams`	`true` includes AI-generated architecture diagrams in review summaries; `false` skips them. Default: `false`.
`external_contributors_require_manual_review`	`true` skips automatic reviews for public-repository PRs from external contributors until a trusted installation member manually triggers one. Default: `false`.
`resolve_threads_when_addressed`	`true` automatically resolves GitHub threads when cubic detects an issue has been addressed; `false` only updates the comment. Default: `true`.
`auto_approve_behavior`	Controls whether auto-approval is disabled, simulated in `shadow` mode, or submitted live to GitHub. Values: `disabled`, `shadow`, `live`.
`auto_approve`	Controls when cubic approves clean reviews. Values: `disabled`, `always`, `low_risk_only`, `custom`.
`auto_approve_custom_prompt`	Custom approval criteria. cubic only uses this field when `auto_approve` is `custom`.
`auto_approve_rules.exclude`	File or directory globs that block auto-approval. If any changed file in a PR matches, cubic will not auto-approve that PR.
`custom_instructions`	Free-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 path	Effect
`reviews.ignore.files`	Skip matching files entirely (same syntax as `.gitignore`).
`reviews.ignore.head_branches`	Ignore PRs based on their source branch.
`reviews.ignore.base_branches`	Ignore PRs targeting specific base branches.
`reviews.ignore.pr_labels`	Ignore PRs with one of these labels. Supports wildcards.
`reviews.ignore.pr_titles`	Ignore PRs whose titles match the provided wildcard patterns.

Common ignore recipes

Use labels or branch names to control when cubic jumps into a review.

Skip review with a label

The most common way to skip a review is by adding a specific label to your PR.

reviews:
  ignore:
    pr_labels:
      - skip-review
      - WIP
      - draft

Skip entire categories of labels

You can use wildcards to ignore any label matching a pattern.

reviews:
  ignore:
    pr_labels:
      - 'no-ai-*'

Custom agents

Each agent needs a name, description, and optional include/exclude glob lists.
Order matters. When you exceed the installation’s rule limit, only the first N agents take effect.
Identical patterns are deduplicated. If an exclude matches an include, the exclude wins.
Agents 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 agents behave in the UI on the Custom agents page.

PR descriptions

Field	Description
`generate`	Toggle AI-authored PR descriptions.
`instructions`	Extra 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

Field	Description
`fix_with_cubic_buttons`	Enable or disable AI-generated “Fix with cubic” calls-to-action inside the issue UI.
`pr_comment_fixes`	Allow cubic to make code changes when someone asks for a fix in a PR comment thread.
`fix_commits_to_pr`	When `true`, fix commits are pushed directly to the PR branch instead of opening a new PR.

Get started

AI code review

cubic in your IDE

Measure impact

Portal

Account & support

Repository configuration

Organization configuration

Configuration hierarchy

Merging behavior

Error handling

Exporting current UI settings

Template `cubic.yaml`

IDE validation

Configuration reference

Reviews section

Core options

Ignore filters

Common ignore recipes

Skip review with a label

Skip entire categories of labels

Custom agents

PR descriptions

Issues

Get started

AI code review

cubic in your IDE

Measure impact

Portal

Account & support

Documentation Index

​Repository configuration

​Organization configuration

​Configuration hierarchy

​Merging behavior

​Error handling

​Exporting current UI settings

​Template cubic.yaml

​IDE validation

​Configuration reference

​Reviews section

​Core options

​Ignore filters

​Common ignore recipes

​Skip review with a label

​Skip entire categories of labels

​Custom agents

​PR descriptions

​Issues

Repository configuration

Organization configuration

Configuration hierarchy

Merging behavior

Error handling

Exporting current UI settings

Template `cubic.yaml`

IDE validation

Configuration reference

Reviews section

Core options

Ignore filters

Common ignore recipes

Skip review with a label

Skip entire categories of labels

Custom agents

PR descriptions

Issues