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

# How to use linked repositories for cross-repo context in code review

> Link sibling repositories so Kody can read contracts and APIs across services when a PR touches a boundary surface.

When your product is split across repositories — for example a frontend that calls a backend API, or a service that depends on a shared contracts package — a single-repo review can miss breakages at the boundary. **Linked repositories** give Kody optional, on-demand context from those sibling codebases during code review.

> **Plan requirement:** Linked repositories are available on **Teams** and **Enterprise** plans (trial included as a preview). Free plans do not include cross-repo context.

This is different from [sharing coding standards across repositories](/knowledge_base/en/how-to-share-standards-across-repositories) (org-level rules and inheritance). Linked repositories share **source context** for a review, not review rules.

## What it does

For a repository under review, you declare up to **3 linked repositories** in the same organization. During the review:

1. Kody first checks whether the PR diff touches anything boundary-shaped — a fast, fixed check that costs nothing.
2. If the diff looks like it touches a **contract surface** (DTOs, exports, string literals, status keys, API-shaped paths, and similar), the cross-repo tools are enabled.
3. Linked repos are **cloned lazily** only when Kody actually needs to read or search them.
4. Findings are still **anchored only to lines in the PR under review** — linked code is evidence, not a second review target.

If no links are configured, the feature is fully off (zero extra cost).

## Configure in the dashboard

Linked repositories are **per repository**, not global. Relationships are directional: links on `frontend` apply only when reviewing PRs in `frontend`.

1. Open **Code Review Settings**.
2. Select a **specific repository** (not Global).
3. Open the **Linked Repositories** page in that repository's menu.
4. Add sibling repos that are already connected to your organization.
5. Optionally set:
   * **Instructions** — free-text hint for Kody (e.g. “REST API this frontend consumes”).
   * **Ref** — optional branch/tag pin. Leave empty to use the automatic ref cascade (below).
6. Save.

You can link at most **3** repositories. Only repos already connected to the same organization are accepted.

## Configure in `kodus-config.yml`

You can also declare links in the repository config file:

```yaml theme={null}
linkedRepositories:
  - repository: "org/backend-api"
    instructions: "REST API this frontend consumes"
    ref: main   # optional pin; omit for same-branch cascade
```

* `repository` (required): full name of a repo connected to the organization (`owner/repo`).
* `instructions` (optional): short description of why the link exists.
* `ref` (optional): pin a branch, tag, or commit. When omitted, Kody uses the ref cascade.

Empty `linkedRepositories: []` means the feature is off.

## How the ref is chosen

For each linked repository, Kody tries refs in this order and uses the first one that clones successfully:

1. **PR description override** for that repo (see below)
2. **Config `ref` pin** (if set)
3. **Open PR** on the linked repo whose head branch matches the PR’s head branch
4. The **PR head branch name** on the linked repo
5. The linked repo’s **default branch**
6. Fallbacks: `main`, then `master`

This keeps multi-repo feature work aligned when the same branch name exists across services, while still falling back safely for normal PRs.

## Override the ref from the PR description

For a one-off review (for example, review against a specific backend PR), mention the linked repo in the **title or description** of the PR under review. Overrides only apply to repositories that are **already linked** in config.

Supported forms:

| Form                | Meaning                                                 |
| ------------------- | ------------------------------------------------------- |
| `owner/repo#123`    | Use the head of PR/MR `#123` on that repo               |
| PR/MR URL           | Same as above (GitHub, GitLab, Bitbucket, Azure DevOps) |
| `owner/repo@branch` | Pin that branch on the linked repo                      |

Examples:

```text theme={null}
Depends on org/backend-api#842
Also needs org/shared-contracts@feature/new-events
```

Later mentions of the same repository win. Mentions of repos that are **not** linked are ignored (they do not create new links).

## When cross-repo context activates (boundary gate)

Even with links configured, Kody does **not** always open sibling repos. A cheap, deterministic gate scans **added lines** in the PR diff and activates only when it finds **boundary surface**, such as:

* String literals (path segments, codes, event names, etc.)
* Exports (`export function`, types, classes, …)
* Enums / types / interfaces
* Object or payload field keys
* Status / state / error-code style identifiers
* Contract-like file paths (`dto`, `schema`, `api`, `client`, `openapi`, `proto`, …)

Internal refactors that only move or reformat non-boundary code typically keep the gate off — so clones and the boundary prompt stay idle.

## What Kody can and cannot do with linked repos

**Can:**

* Search and read files in linked repositories when the gate is on
* Use your **instructions** to understand the relationship
* Cite linked code as supporting evidence in a finding on the current PR

**Cannot / will not:**

* Post review comments on files that exist only in a linked repository
* Review the entire linked repo as if it were the PR
* Link repositories outside the organization or that are not connected to Kodus
* Exceed the soft cap of 3 linked repositories per reviewing repo

## Transparency at the end of the review

When linked repositories were part of the run, review metadata records which repos were configured, which refs were resolved (and from which source: description, pin, open PR, head branch, or default), and whether the boundary gate activated. Failed or skipped links surface as warnings rather than failing the whole review.

## Recommended setups

| Scenario                   | Link from                        | Typical instructions                            |
| -------------------------- | -------------------------------- | ----------------------------------------------- |
| Frontend ↔ backend         | Frontend → backend API repo      | “HTTP/REST client contracts this UI depends on” |
| Service ↔ shared contracts | Service → contracts/package repo | “Shared events, DTOs, and protobufs”            |
| BFF ↔ multiple backends    | BFF → up to 3 backend repos      | One short line per service boundary             |

Prefer **narrow, directional** links (the consumer points at the producer) over linking every repo to every other.

## Related guides

* [Linked Repositories settings reference](/how_to_use/en/code_review/configs/linked_repositories) — the settings page, field by field

* [How to share coding standards across repositories](/knowledge_base/en/how-to-share-standards-across-repositories) — org-level rules and inheritance (not source context)

* [How to review PRs with project-specific context](/knowledge_base/en/how-to-review-prs-with-project-context) — memories, file references, custom prompts, MCP

* [How to reduce code review noise](/knowledge_base/en/how-to-reduce-code-review-noise) — keep reviews focused when you add more context