> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubic.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure with cubic.yaml
> Version-control your AI review settings with a single YAML file in each repository.
## 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`.
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.
## Branches
cubic reads configuration only from the default branch:
* For repository configuration, this is the default branch of that repository.
* For organization configuration, this is the default branch of the `cubic-config` repository.
cubic does not read configuration from feature branches. Changes are picked up automatically when you push to the default branch.
## 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.
**Organization config** (`cubic-config/cubic.yaml`):
```yaml theme={null}
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`):
```yaml theme={null}
version: 1
reviews:
sensitivity: low # Override org's "high"
custom_rules:
- name: API validation
description: Check API contracts
- name: React style guide
file_paths:
- docs/react-style-guide.md
- docs/component-rules.md
```
**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" and "React style guide" (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.
1. Go to the [AI review settings page](/ai-review/ai-review-settings) 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.
## 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 theme={null}
# 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_external_contributors: false
exclude:
- '**/migrations/**'
- infra/**
only_files:
- docs/**
# PR metadata gates. exclude_* blocks on any match, only_* is an allowlist.
exclude_labels:
- do-not-auto-approve
only_authors:
- renovate[bot]
- dependabot[bot]
only_base_branches:
- main
# Master switch: automatic triggers below only fire when this is `automatic`.
ultrareview: manual # disabled | manual | automatic
auto_ultrareview: disabled
auto_ultrareview_custom_prompt: |
Run an ultrareview when auth or payment flows change.
# When ultrareview is automatic, file patterns trigger even when auto_ultrareview is disabled —
# remove this list entirely to fully turn auto-trigger off.
auto_ultrareview_file_patterns:
- '**/migrations/**'
custom_instructions: |
Outline any project-specific guidance you want included in reviews.
# Optional ignore filters; PR filters suppress automatic reviews when they match.
ignore:
files:
- path/to/generated/**
head_branches:
- wip/*
pr_labels:
- skip-review
max_changed_lines: 5000
# 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.*
- name: Enforce style guide
description: Enforce the repository style guide.
file_paths:
- docs/style-guide.md
- docs/review-rules.md
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
auto_fix_sign_commits: false
coding_agent_provider: cubic # cubic | cursor_cloud_agent
```
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](/ai-review/ai-review-settings) 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`](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](/ai-review/ai-review-settings) 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` automatically reviews new commits pushed to open PRs (only new issues are posted); `false` skips automatic incremental reviews. Manual requests with `@cubic-dev-ai incremental review` work with either value. 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. |
| `auto_approve_rules.only_files` | File or directory globs that allow auto-approval. Every current and previous changed path must match at least one glob. Never-auto-approve rules take precedence. |
| `auto_approve_rules.exclude_external_contributors` | `true` keeps reviewing public-repository PRs from external contributors, but prevents cubic from auto-approving them. Default: `false`. |
| `auto_approve_rules.exclude_authors` / `only_authors` | Gate auto-approval on the PR author. `exclude_*` blocks any match; `only_*` is an allowlist. Logins match case-insensitively, and brackets are literal so both `renovate[bot]` and `*[bot]` work. |
| `auto_approve_rules.exclude_head_branches` / `only_head_branches` | Same gates on the PR source branch. |
| `auto_approve_rules.exclude_base_branches` / `only_base_branches` | Same gates on the branch the PR targets. |
| `auto_approve_rules.exclude_labels` / `only_labels` | Same gates on PR labels. Labels match exactly (case-insensitive) rather than as globs. |
| `auto_approve_rules.exclude_titles` / `only_titles` | Same gates on the PR title, matched as glob patterns. |
| `ultrareview` | Master switch for ultrareviews. `disabled` blocks all ultrareviews (manual and automatic), `manual` allows only manual triggers (default), `automatic` also enables the automatic triggers below. |
| `auto_ultrareview` | Controls when cubic auto-triggers an [ultrareview](/ai-review/ultrareview). Values: `disabled`, `high_risk_only`, `custom`. |
| `auto_ultrareview_custom_prompt` | Custom criteria describing which PRs warrant an ultrareview. cubic only uses this field when `auto_ultrareview` is `custom`. |
| `auto_ultrareview_file_patterns` | File or directory globs that always trigger an ultrareview. If any changed file in a PR matches, cubic runs an ultrareview. |
| `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](/ai-review/ai-review-settings). All lists accept glob strings, and duplicates/blank entries are dropped automatically. Pull request filters suppress automatic reviews; an explicit `@cubic-dev-ai review` request can still start a review on a matching PR. File filters continue to apply during manually requested reviews.
| YAML path | Effect |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reviews.ignore.files` | Skip matching files entirely (same syntax as `.gitignore`). |
| `reviews.ignore.head_branches` | Suppress automatic review based on the PR source branch. |
| `reviews.ignore.base_branches` | Suppress automatic review for PRs targeting specific branches. |
| `reviews.ignore.pr_labels` | Suppress automatic review when a PR label matches. Supports wildcards. |
| `reviews.ignore.pr_titles` | Suppress automatic review when the PR title matches a wildcard pattern. |
| `reviews.ignore.max_changed_lines` | Store a positive-integer automatic-review threshold (up to 2,147,483,647) for reviewable added plus deleted lines. cubic preserves values above 50,000 but applies an effective 50,000-line ceiling to every review. Manual triggers can bypass a lower configured threshold, but not the effective ceiling. |
### Common ignore recipes
Use labels or branch names to control when cubic jumps into a review.
#### Review agent PRs only when requested
Use a title prefix or branch namespace for agent-authored PRs. cubic will skip automatic reviews, including push-triggered incremental reviews, for matching PRs, while a teammate can request one when the PR is ready with `@cubic-dev-ai review`.
```yaml theme={null}
reviews:
ignore:
head_branches:
- 'agent/**'
pr_titles:
- 'no-auto-review:*'
```
`agent/**` matches nested branch paths such as `agent/batch/change`; `agent/*` only matches one path segment. The title prefix avoids bracket syntax, which glob matchers interpret specially.
#### Skip review with a label
The most common way to skip a review is by adding a specific label to your PR.
```yaml theme={null}
reviews:
ignore:
max_changed_lines: 5000
pr_labels:
- skip-review
- WIP
- draft
```
#### Skip entire categories of labels
You can use wildcards to ignore any label matching a pattern.
```yaml theme={null}
reviews:
ignore:
pr_labels:
- 'no-ai-*'
```
### Custom agents
* Each agent needs a `name` plus inline `description` text, an ordered `file_paths` list, or both. Optional `include`/`exclude` glob lists apply to both modes.
* 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](/ai-review/custom-agents).
* File-backed agents use repo-relative paths only. Absolute paths, globs, parent-directory traversal, directories, binary files, and unreadable files are rejected or surfaced as warnings.
* The description and file contents are concatenated in the order listed. cubic uses only the first 10,000 characters per custom agent; characters after that limit are not included in the review prompt.
* YAML and Markdown files referenced by file-backed agents are treated as plain text, not parsed as structured rule definitions.
* In organization config, `file_paths` entries are relative to each target repository, not to the `cubic-config` repository. The files must exist in every repository where the org-level agent should apply.
```yaml theme={null}
reviews:
custom_rules:
- name: Enforce style guide
description: Enforce the repository style guide.
file_paths:
- docs/style-guide.md
- docs/react.md
include:
- "src/**/*.tsx"
```
## 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. |
| `cubic_review_link` | Include a "Review in cubic" link. Default: `true`. |
| `skip_if_author_description` | Skip AI description generation on new PRs when the author already wrote a substantive description. Empty or template-only descriptions still get an AI description. Default: `false`. |
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. |
| `auto_fix_sign_commits` | When `true`, cubic signs the commits it pushes so GitHub marks them as verified. This applies only to the `cubic` coding agent; the Cursor agent always signs its commits. |
| `coding_agent_provider` | Which coding agent applies automatic fixes: `cubic` (built-in agent) or `cursor_cloud_agent` (dispatches a Cursor cloud agent; requires Cursor configuration). |