The number of linked repositories you can configure depends on your plan. Automatic repository linking is available only on paid Pro+ plans and Enterprise plans. See Plans and pricing for details.
Use cases
Multi-repo analysis is most valuable when your codebase is split across several repositories that share contracts or dependencies:- API contracts — When a backend API changes, frontend or mobile repositories may need coordinated updates.
- Microservices architectures — A change to a service’s REST API may break consumers in other repositories.
- Shared libraries — Modifications to a shared utility or type definition can have ripple effects across multiple repositories.
- Database schemas — Schema changes can affect all services that query the same data model.
How it works during reviews
When you submit a pull request, CodeRabbit inspects the changes and determines whether they may affect the linked repositories. If the research agent finds relevant cross-repository impact, it includes those findings in the review. If the changes are self-contained and have no cross-repo effect, the agent does not produce findings (this is expected behavior and does not indicate a misconfiguration). By default, CodeRabbit compares your changes against each linked repository’s default branch. When the change you depend on hasn’t merged yet, you can point CodeRabbit at a specific branch or pull request of a linked repository instead.Where findings appear
Cross-repository findings appear in the PR under Review details > Additional context used, grouped by linked repository name. When automatic repository linking contributes repositories, the Review info section also lists the repositories CodeRabbit considered and labels each one asmanual or auto-detected. Findings also surface in inline review comments and comment replies when relevant.
When CodeRabbit reviews a linked repository against a specific branch or pull request rather than its default branch, the Review info section notes which ref was used — for example, reviewed against open PR #123 feat/orders-v2 instead of the default branch (references on GitLab are labeled as merge requests). Repositories reviewed against their default branch are listed without an annotation. See Specifying a branch or pull request to review against.
To see the Review details section, enable review_details in your configuration:
.coderabbit.yaml
Setting it up
Linked repositories are configured through the CodeRabbit web interface or via your.coderabbit.yaml file. In most cases, you want to configure links at the repository level, configuring linked repositories at the organization level applies the same linked repository to every repository in your organization, which is rarely what you want. If you need to share a default linked repository across repos while still allowing per-repo overrides, see configuration inheritance.
For larger or fast-changing dependencies, Automatic repository linking lets CodeRabbit discover and maintain the list for you.
- YAML Configuration
- Web Interface
Add a
linked_repositories section under knowledge_base in your .coderabbit.yaml file inside the repository you want to configure (for example, your frontend repo):.coderabbit.yaml
Configuration fields
| Field | Required | Description |
|---|---|---|
automatic_repository_linking | No | Enables CodeRabbit to automatically detect related repositories for review context. Requires a paid Pro+ plan or an Enterprise plan. On other plans, setting this field to true in .coderabbit.yaml is ignored. Defaults to false. |
repository | Yes | Repository in org/repo format (GitHub and Bitbucket), project/repo format (Azure DevOps), or group/subgroup/repo format (GitLab) |
instructions | No | Description and guidance on what the repository contains (max 2,000 characters) |
Automatic repository linking
Instead of maintaining a list of related repositories by hand, you can let CodeRabbit discover and link them automatically. When enabled, CodeRabbit scans your organization’s repositories and infers relationships by examining import statements, dependency manifests, API consumption, and broader architectural patterns, then describes each relationship so the review agent can reason about cross-repository impact. Detection runs progressively after you enable the feature. CodeRabbit discovers relationships over time as it reviews more pull requests, so the set of automatically linked repositories grows gradually rather than appearing all at once. Reviews opened immediately after enabling may not yet include automatically discovered repositories. Automatically linked repositories supplement your manually configured ones. Manually linked repositories are always preserved; auto-detected links fill any remaining slots.Automatic repository linking is available only on paid Pro+ plans and Enterprise plans. It counts toward your plan’s linked-repository limit. CodeRabbit will not link more repositories than your plan allows.
- YAML Configuration
- Web Interface
Set
automatic_repository_linking under knowledge_base in the repository’s .coderabbit.yaml:.coderabbit.yaml
Viewing automatically linked repositories
After you enable automatic repository linking, CodeRabbit surfaces what it has detected in the Auto-linked repositories tab, under a repository’s Knowledge Base settings. The tab is read-only and scoped to a single repository: it lists the repositories CodeRabbit links during reviews of the repository you are viewing, so open a specific repository’s settings to see its list.You can only view this list after automatic repository linking is enabled. The editable Automatic repository linking toggle lives in the Knowledge Base settings tab; while it is off, the Auto-linked repositories tab points you back there to turn it on instead of showing a list. Because detection runs progressively, the tab is also empty right after you enable the feature and fills in as CodeRabbit reviews more pull requests.
- Search and sort by repository name to locate a repository in a long list.
- Filter by status — Enabled or Disabled. The tab shows only enabled repositories by default; add Disabled to the status filter (or clear the filter) to see repositories you have turned off.
- Open a repository’s details by selecting its row. A read-only drawer shows the repository’s status and the instructions CodeRabbit detected for it.
auto-detected.
Disabling an automatically linked repository
Automatic linking is best-effort discovery, so CodeRabbit may link a repository you would rather keep out of reviews. You can turn off an individual repository without disabling automatic linking for the whole repository:Open the Auto-linked repositories tab
In the repository’s settings, go to Knowledge Base > Auto-linked repositories.
- It is excluded from reviews entirely. CodeRabbit no longer researches or references it, and it no longer appears in the Review info list.
- It is marked Disabled and greyed out in the tab, and hidden by the default status filter.
- It frees a slot against your plan limit. A disabled repository no longer counts toward your linked-repository limit, so CodeRabbit can link another repository it discovers in its place.
- Your choice persists. CodeRabbit keeps the repository disabled even if it rediscovers it during a later review. Re-enable it from the same drawer whenever you want it back.
Specifying a branch or pull request to review against
By default, CodeRabbit reviews your pull request against the default branch of each linked repository. When the change you depend on lives on a feature branch or in an open pull request that hasn’t merged yet, you can tell CodeRabbit which ref of a linked repository to review against by referencing it in the pull request description. This is useful for coordinated changes across repositories — for example, a frontend pull request that depends on a backend API change that hasn’t merged yet. Pointing CodeRabbit at the companion branch or pull request lets it review against the code that will ship together, instead of a default branch that doesn’t contain those changes yet.A reference only takes effect when the repository is already linked, either manually or through automatic repository linking. Referencing a repository that is not linked has no effect and does not add it to the linked set.
Supported reference formats
Add any of the following to the pull request description. CodeRabbit resolves the reference directly against the platform, independent of the referenced pull request’s age or author.| What you reference | GitHub | GitLab |
|---|---|---|
| Pull request / merge request by number | owner/repo#123 | group/subgroup/repo#123 |
| Pull request / merge request by URL | https://github.com/owner/repo/pull/123 | https://gitlab.com/group/subgroup/repo/-/merge_requests/123 |
| Branch by URL | https://github.com/owner/repo/tree/branch-name | https://gitlab.com/group/subgroup/repo/-/tree/branch-name |
| Branch by name | owner/repo@branch-name | group/subgroup/repo@branch-name |
How references are resolved
- The repository must already be linked. References to repositories that are not linked are ignored and do not expand the linked set.
- GitHub and GitLab only. Manual reference selection is not available on Bitbucket, Azure DevOps, or other platforms.
- Read access is required. The CodeRabbit bot must be able to read the referenced repository, which is the same access required to link it.
- Referenced pull requests must be open. A closed, merged, or nonexistent pull request reference is ignored, and CodeRabbit falls back to the default branch.
Automatic same-branch matching
If you don’t reference anything explicitly, CodeRabbit still checks whether a linked repository has a branch whose name matches your pull request’s head (source) branch. When it finds one, CodeRabbit reviews against that branch — preferring an open pull request on the branch, otherwise the branch itself — so identically named branches across repositories are picked up automatically with no description needed. An explicit reference always takes precedence over automatic same-branch matching.The branch or pull request CodeRabbit selects for each linked repository appears in the Review info section of the review summary. See Where findings appear.
Platform requirements
The CodeRabbit bot must have read access to all linked repositories. Same platform only: All linked repositories must be on the same platform as the pull request under review. You cannot link a GitHub repository to a GitLab repository, because access tokens are platform-specific.| Platform | Requirement |
|---|---|
| GitHub | The CodeRabbit GitHub App must be installed on all linked repositories. Inaccessible repositories are skipped, and a warning appears in the review summary. |
| GitLab | The bot token must have read access. Tokens are typically scoped to the group or instance. |
| Bitbucket Cloud | The bot token must have read access. Tokens are scoped to the workspace. |
| Bitbucket Data Center | The HTTP access token must have read access. Tokens are scoped to the project or repository. |
| Azure DevOps | The PAT must have read access. Tokens are scoped to the organization. |
On GitHub, linked repositories can span multiple organizations as long as the CodeRabbit GitHub App is installed in each organization. Other platforms scope access tokens to the group, workspace, or organization.
Configuration inheritance
When configuration inheritance is enabled, organization-level and repository-levellinked_repositories settings are merged. Repository-level entries take priority: if both levels define the same repository, the repository-level instructions are used.
After merging, the list is truncated to your plan’s limit, with repository-level entries preserved. If automatic repository linking is enabled, auto-detected links fill only the remaining slots after manual organization-level and repository-level entries are merged and deduplicated. If any repositories are dropped during this process, a warning appears in the review summary showing which repositories were kept and which were skipped.
Plan limits
The number of linked repositories you can activate depends on your plan. See Plans and pricing for current limits. Both manually configured and auto-detected repositories count toward the limit. Manual entries are always filled first; auto-detected repositories use whatever slots remain. Disabled automatically linked repositories are the exception: they no longer count toward the limit, so disabling one frees a slot for another repository CodeRabbit discovers. If your.coderabbit.yaml defines more linked repositories than your plan allows:
- Your configuration is preserved. CodeRabbit does not delete or reject entries that exceed your plan’s limit.
- Only the first N items are active. CodeRabbit evaluates entries in the order they appear in your configuration, up to your plan’s limit. Entries beyond the limit are ignored during reviews.
- Upgrade to restore full access. Moving to a higher plan immediately activates all configured entries up to the new limit.
Troubleshooting
If cross-repository context is not appearing in reviews, work through these checks in order:Linked repositories not configured?
Linked repositories not configured?
Check your
.coderabbit.yaml or the Settings UI for a linked_repositories section, or enable knowledge_base.automatic_repository_linking if automatic linking is available for your organization. Multi-repo analysis is not enabled by default.Auto-detected repository missing?
Auto-detected repository missing?
Manual linked repositories consume plan slots first. If you expected an auto-detected repository to appear, confirm that
automatic_repository_linking is enabled, the repository is not disabled in the Auto-linked repositories tab, the bot can read the related repository, and your plan has an available linked-repository slot after manual links are applied.Automatic repository linking setting ignored?
Automatic repository linking setting ignored?
Automatic repository linking requires a paid Pro+ plan or an Enterprise plan. If your organization is on any other plan, CodeRabbit does not enable automatic repository linking from the app and ignores
knowledge_base.automatic_repository_linking: true in .coderabbit.yaml.Linked repository is the same as the current repo?
Linked repository is the same as the current repo?
Multi-repo analysis filters out the repository currently being reviewed. Make sure you have linked a different repository.
Bot does not have access?
Bot does not have access?
On GitHub, the CodeRabbit App must be installed on the linked repository. On other platforms, the bot token must have read access. If a linked repository is inaccessible, a warning appears in the review summary identifying the repository and the specific error.
Pull request has no cross-repo impact?
Pull request has no cross-repo impact?
If the changes in the pull request are self-contained, the research agent will not produce cross-repository findings. This is expected — the absence of findings does not mean the feature is broken.
What’s next
Knowledge Base overview
Return to the Knowledge Base overview for all adaptive review features
CodeRabbit Learnings
Use learnings to train CodeRabbit on your team’s specific preferences
Model Context Protocol
Extend CodeRabbit’s understanding with external tools via the MCP