> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coderabbit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Repo Analysis

> Link related repositories so CodeRabbit can detect breaking changes, API mismatches, and dependency issues that cross repository boundaries during code review.

export const Hint = ({type, children, headline, tip, href, cta}) => {
  const TIPS = {
    learnings: {
      headline: "Learnings",
      tip: "Review preferences CodeRabbit learns from your chat conversations and applies automatically to future reviews.",
      cta: "Learn about Learnings",
      href: "/knowledge-base/learnings",
      content: "Learnings"
    },
    walkthrough: {
      headline: "PR Walkthrough",
      tip: "A structured comment posted by CodeRabbit at the top of every pull request, summarizing changes, sequence diagrams, review effort, and more.",
      cta: "Learn about PR Walkthroughs",
      href: "/pr-reviews/walkthroughs",
      content: "Walkthrough"
    },
    "finishing-touches": {
      headline: "Finishing Touches",
      tip: "Post-review agentic actions (Autofix, writing docstrings or unit tests, and more) you trigger from a PR comment or a checkbox in the Walkthrough.",
      cta: "See all Finishing Touches",
      href: "/finishing-touches",
      content: "Finishing Touches"
    },
    "coding-plan": {
      headline: "Coding Plan",
      tip: "A detailed, codebase-aware implementation plan CodeRabbit generates from an issue or description, ready to hand off to any coding agent.",
      cta: "Learn about Coding Plans",
      href: "/plan",
      content: "Coding Plan"
    },
    "knowledge-base": {
      headline: "Knowledge Base",
      tip: "The collected context sources CodeRabbit draws on during reviews: Learnings, Code Guidelines, issue trackers, connected MCP servers, and cross-repo analysis.",
      cta: "Explore the Knowledge Base",
      href: "/knowledge-base",
      content: "Knowledge Base"
    },
    "path-instructions": {
      headline: "Path Instructions",
      tip: "Custom review rules that only apply to files matching a glob pattern, e.g. 'src/controllers/**'.",
      cta: "Configure path instructions",
      href: "/configuration/path-instructions",
      content: "Path Instructions"
    },
    "coderabbit-review": {
      headline: "CodeRabbit Review",
      tip: "An improved code inspection interface that reorganizes a pull request from a flat file list into a structured, layer-by-layer walkthrough with range-specific summaries and diagrams.",
      cta: "Learn about CodeRabbit Review",
      href: "/pr-reviews/coderabbit-review",
      content: "CodeRabbit Review"
    },
    scope: {
      headline: "Scope",
      tip: "A named set of repositories, connections, and spend limits that controls what CodeRabbit Agent can access in a given Slack conversation.",
      cta: "Learn about Scopes",
      href: "/slack-agent/scopes",
      content: "Scope"
    },
    "coderabbit-agent": {
      headline: "CodeRabbit Agent for Slack",
      tip: "An AI agent built into Slack that investigates issues, generates implementation plans, and opens pull requests right from the Slack threads.",
      cta: "Explore CodeRabbit Agent",
      href: "/slack-agent",
      content: "CodeRabbit Agent"
    },
    "configuration-inheritance": {
      headline: "Configuration Inheritance",
      tip: "A setting that merges configuration values across multiple levels — repository YAML, central YAML, and UI settings — instead of using only the highest-priority source.",
      cta: "Learn about Configuration Inheritance",
      href: "/configuration/configuration-inheritance",
      content: "Configuration Inheritance"
    }
  };
  const defaults = TIPS[type] || ({});
  return <Tooltip headline={headline ?? defaults.headline} tip={tip ?? defaults.tip} cta={cta ?? defaults.cta} href={href ?? defaults.href}>
      {children ?? defaults.content}
    </Tooltip>;
};

export const EnterprisePlanBadge = ({tip = "This feature is available exclusively as part of the Enterprise plan. Please refer to our pricing page for more information about our plans and features.", title = "Enterprise Plan", cta = "Read more", href = "https://coderabbit.ai/pricing", disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="building-2" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

export const ProPlusPlanBadge = ({tip = "This feature is available as part of the Pro+ plan and Enterprise plan. Please refer to our pricing page for more information about our plans and features.", title = "Pro+ Plan", cta = "Read more", href = "https://coderabbit.ai/pricing", disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="shield-plus" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

export const ProPlanBadge = ({tip = "This feature is available as part of the Pro, Pro+ and Enterprise plans. Please refer to our pricing page for more information about our plans and features.", title = "Pro Plan", cta = "Read more", href = "https://coderabbit.ai/pricing", disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="shield-check" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

export const GitLabBadge = ({tip = "This feature is available on GitLab.", title = "GitLab", cta, href, disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="gitlab" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

export const GitHubBadge = ({tip = "This feature is available on GitHub and GitHub Enterprise.", title = "GitHub", cta, href, disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="github" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

export const AllPlatformsBadge = ({tip = "This feature is available on all supported platforms: GitHub, GitLab, Azure DevOps, and Bitbucket.", title = "All Platforms", cta, href, disabled = false}) => {
  return <Tooltip tip={tip} cta={cta} href={href}>
        <Badge icon="globe" disabled={disabled || undefined}>
            {title}
        </Badge>
    </Tooltip>;
};

<AllPlatformsBadge /> | <ProPlanBadge tip="Manual repository linking is available on the Pro plan. Automatic repository linking requires Pro+ or Enterprise." /> <ProPlusPlanBadge tip="Manual and automatic repository linking are both available on the Pro+ plan." /> <EnterprisePlanBadge tip="Manual and automatic repository linking are both available on the Enterprise plan." />

Many projects are built from multiple interdependent subprojects, for example: a backend service, a frontend app, a mobile client — that share APIs, type definitions, or database schemas. When they're in separate repositories, a change in one can silently break another. To enable CodeRabbit to detect these cross-repository impacts during code review, configure linked repositories for the repositories that depend on each other or enable automatic repository linking when it is available for your organization.

<Info>
  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](/management/plans#linked-repositories) for details.
</Info>

## 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](#specifying-a-branch-or-pull-request-to-review-against) of a linked repository instead.

## Where findings appear

Cross-repository findings appear in the PR <Hint type="walkthrough" /> 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 as `manual` 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](#specifying-a-branch-or-pull-request-to-review-against).

To see the **Review details** section, enable [`review_details`](/reference/configuration) in your configuration:

```yaml .coderabbit.yaml theme={null}
reviews:
  review_details: true
```

## 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](/configuration/configuration-inheritance).

For larger or fast-changing dependencies, [Automatic repository linking](#automatic-repository-linking) lets CodeRabbit discover and maintain the list for you.

<Tabs>
  <Tab title="YAML Configuration">
    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):

    ```yaml .coderabbit.yaml theme={null}
    knowledge_base:
      linked_repositories:
        - repository: "myorg/backend-api"
          instructions: "Contains REST API endpoints and database models"
    ```
  </Tab>

  <Tab title="Web Interface">
    <Steps>
      <Step title="Open the repository's Knowledge Base settings">
        In the [CodeRabbit app](https://app.coderabbit.ai), navigate to the specific repository you want to configure (for example, your frontend repo), then go to **Knowledge Base** > **Linked Repositories**.
      </Step>

      <Step title="Add a linked repository">
        Click **Add** and enter the repository path in the format used by your platform:
        `org/repo` for GitHub and Bitbucket, `project/repo` for Azure DevOps, or
        `group/subgroup/repo` for GitLab.
      </Step>

      <Step title="Add a description (optional)">
        Optionally provide a description and guidance on what this repository contains so CodeRabbit knows where to focus its search. For example: *"Contains REST API endpoints and database models."*
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Configuration fields

| Field                          | Required | Description                                                                                                                                                                                                                                                               |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `automatic_repository_linking` | No       | Enables CodeRabbit to [automatically detect](#automatic-repository-linking) 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

<ProPlusPlanBadge />

<EnterprisePlanBadge />

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.

<Info>
  Automatic repository linking is available only on paid Pro+ plans and Enterprise plans. It counts toward your plan's [linked-repository limit](#plan-limits). CodeRabbit will not link more repositories than your plan allows.
</Info>

<Tabs>
  <Tab title="YAML Configuration">
    Set `automatic_repository_linking` under `knowledge_base` in the repository's `.coderabbit.yaml`:

    ```yaml .coderabbit.yaml theme={null}
    knowledge_base:
      automatic_repository_linking: true
    ```
  </Tab>

  <Tab title="Web Interface">
    <Steps>
      <Step title="Open the repository's Knowledge Base settings">
        In the [CodeRabbit app](https://app.coderabbit.ai), navigate to the repository, then open **Knowledge Base** settings.
      </Step>

      <Step title="Enable automatic repository linking">
        Turn on **Automatic repository linking**. CodeRabbit discovers and links related repositories for you, in addition to any you have configured manually.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### 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.

<Info>
  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.
</Info>

From the tab you can:

* **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.

Automatically linked repositories also appear in the pull request review comment under **Review info**, where each repository is labeled `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:

<Steps>
  <Step title="Open the Auto-linked repositories tab">
    In the repository's settings, go to **Knowledge Base** > **Auto-linked repositories**.
  </Step>

  <Step title="Select the repository">
    Click the repository's row to open its detail drawer.
  </Step>

  <Step title="Disable or re-enable it">
    Choose **Disable** to exclude the repository from reviews, or **Enable** to include it again.
  </Step>
</Steps>

When you disable an automatically linked repository:

* **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](#plan-limits).** 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

<GitHubBadge />

<GitLabBadge />

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.

<Info>
  A reference only takes effect when the repository is **already linked**, either [manually](#setting-it-up) or through [automatic repository linking](#automatic-repository-linking). Referencing a repository that is not linked has no effect and does not add it to the linked set.
</Info>

### 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.

<Info>
  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](#where-findings-appear).
</Info>

## 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.                                                                                       |

<Info>
  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.
</Info>

## Configuration inheritance

When [configuration inheritance](/configuration/configuration-inheritance) is enabled, organization-level and repository-level `linked_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](/management/plans#linked-repositories) 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](#disabling-an-automatically-linked-repository) 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:

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={1}>
  <Card title="Knowledge Base overview" href="/knowledge-base" icon="book" horizontal>
    Return to the Knowledge Base overview for all adaptive review features
  </Card>

  <Card title="CodeRabbit Learnings" href="/knowledge-base/learnings" icon="brain" horizontal>
    Use learnings to train CodeRabbit on your team's specific preferences
  </Card>

  <Card title="Model Context Protocol" href="/knowledge-base/mcp-context" icon="plug" horizontal>
    Extend CodeRabbit's understanding with external tools via the MCP
  </Card>
</CardGroup>