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

# Linked Repositories

> Let Kody read sibling repositories as context during review — for cross-repo contracts, and for code your repository depends on but doesn't contain.

Linked Repositories let Kody read other repositories of your organization as **read-only context** while reviewing a pull request. Without it, the review sees exactly one thing: the repository under review, checked out at the PR's head. Anything that lives in another repository — a service you call, a library you import, a git submodule — is invisible.

Available on **Teams and Enterprise** plans. Configured **per repository** — there is no global default, because relationships are directional: linking `frontend → backend-api` means *reviews of `frontend`* may consult `backend-api`, not the other way around. Link both directions explicitly if both teams want the check.

## When you need it

Three situations, all common, all invisible to a single-repo review:

1. **Producer/consumer contract breakage.** The backend renames an API field and the frontend still reads the old one; a producer adds an enum value no consumer handles; writer and reader derive the same cache key differently. The contract is split across two repos and enforced by nothing.

2. **The code your repo depends on is not in your repo.** Git submodules, vendored internal packages, shared libraries pulled at build time. The review clones your repository *without submodules* and *without fetching packages*, so a submoduled or build-time dependency is an empty directory (or an import the agent can't follow) during review. If your canonical types, rules, or clients live in such a repo, linking it is the only way the review can read them.

3. **The same business rule reimplemented per channel or service.** Pricing, availability, validation, order-state transitions that exist once in a canonical place and get copied, approximately, elsewhere. Linking the canonical repo lets the agent compare against the source of truth instead of guessing.

<Note>
  **What the review already sees without this feature:** the full repository under review (not just the diff) at the PR's head commit, plus the PR description. It can grep and read any file in that checkout. It cannot see other repositories, submodule contents, or installed dependencies.
</Note>

Linked repositories do **not** cover contracts that live outside your code — a third-party API's validation rules, for example, are not discoverable in any linked repository.

## What you get

A concrete example. Your frontend PR adds this error handling:

```ts theme={null}
const isNotApproved =
    error.response?.data?.error === 'INTEGRATION_NOT_APPROVED';
```

With the backend linked, Kody checks the other side of that contract and comments on the PR:

> **Bug · medium** — \[cross-repo] The frontend checks `error.response?.data?.error` for `INTEGRATION_NOT_APPROVED`, but the backend's `sendError` (`src/api/response.ts`) returns the code in a `message` field. The not-approved branch never matches, so users always see the generic error toast. Read `data.message` instead.

The review summary also shows what was consulted: **Additional context used:** `org/backend-api@main`.

### Where findings land

* Every comment lands on a line of **your PR's diff**. Linked-repo code is quoted inside the comment as evidence, tagged `[cross-repo]`, with the counterpart file named. Kody never comments on, files findings against, or modifies the linked repository.
* Findings are only raised with confirmed evidence from the counterpart file — "this literal must match the backend" without proof is not emitted.
* The **Additional context used** line appears only when a linked repository was actually read during the review. No line means it wasn't consulted (see below for why that happens).

## How it works

When a pull request in a repository with linked repositories touches boundary surface, Kody's review agent can search and read the linked repositories — the same way it greps your own repo — to verify that both sides of a contract still agree. Linked repos are fetched lazily, only when the agent first reads them.

### What arms the pass

Configuring a link is not enough on its own. Before the review, a cheap deterministic check scans the **added lines** of the PR diff and enables cross-repo tools only when it finds *boundary surface*:

* string literals (codes, event names, path segments, header names)
* exported symbols (`export function/const/class/type/interface/enum`)
* enum, type or interface members
* object / payload / DTO field keys
* status-, state-, error-code-like identifiers (`status`, `code`, `errorCode`, `kind`, `event`, `key`, …)
* contract-ish file paths (`dto/`, `schema/`, `api/`, `types/`, `clients/`, `openapi`, `proto`, …)

Internal-only refactors — renaming a private helper, moving code around, formatting — typically hit none of these, so the linked repositories are never fetched and the review runs exactly as a single-repo review. This is intentional: it keeps the pass off for diffs where it can't find anything.

### When you see nothing

If a PR in a repository with linked repositories shows **no** `Additional context used` line, one of these happened, in rough order of likelihood:

1. The diff had no boundary surface (gate stayed off — expected for refactors).
2. The gate was on, but the agent didn't need the linked repo to reach its conclusions.
3. The linked repository couldn't be fetched (permissions, timeout) — the review continues without it.
4. The linked repository isn't connected to this Kodus organization, or the organization's plan doesn't include the feature — the link is ignored.

The first two are the feature working as designed. To confirm a link is wired correctly, open a PR that *does* change a shared literal, DTO field or exported type — that both arms the gate and gives the agent a reason to look across.

<Info>
  * Only repositories **already connected to the same Kodus organization** can be linked (Kody reuses your existing Git integration — no extra tokens).
  * Up to **3 linked repositories** per repository.
  * Access is read-only. Kody never pushes to, comments on, or modifies a linked repository.
  * If a linked repository can't be fetched (permissions, timeout), the review continues normally without it.
</Info>

## Adding a linked repository

### In the web app

Go to **Code Review Settings → *your repository* → Linked Repositories**, pick a repository from the list (only connected repos appear), and save. Each link has two optional fields, described below.

### In `kodus-config.yml`

`linkedRepositories` is also a config-file key, so links can live in version control next to the rest of your review settings:

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

* `repository` (required) — full name of a repository connected to the organization (`owner/repo`).
* `instructions`, `ref` — same meaning as the fields in the web app (below).

How the file interacts with the web settings follows the normal [config-file rules](/en/how_to_use/code_review/configs/general#config-priority): the file is only read when `kodusConfigFileOverridesWebPreferences` is enabled for the repository (**Settings → Code Review → the repository → General**), it is read from the repository's **default branch**, and the file's `linkedRepositories` list **replaces** the web list for that repository (the lists are not merged; `linkedRepositories: []` in the file turns the feature off). The plan requirement applies regardless of where the links are declared.

### Instructions

A free-text hint that tells the review agent **what this link is for and where to look**. Kody works without it, but a good instruction makes the cross-repo pass faster and more accurate — it's the difference between the agent exploring the linked repo from scratch and going straight to the relevant code.

Good instructions name the relationship and the load-bearing paths:

```text theme={null}
REST API this dashboard consumes. Error responses are built by
src/api/response.ts — check error codes against it.
```

```text theme={null}
Shared order state machine. Status enums live in
src/domain/order-status.ts; we must handle every value it defines.
```

For a linked library or submodule (use case 2 above), say that the code is *not* in this repo and what the agent should check against:

```text theme={null}
Canonical library of business rules, types and clients. Consumed here as a
git submodule, so its source is not in this repo. Validation rules live in
src/rules/, API clients in src/clients/ — check field names and status
values against them.
```

Weak instructions restate the obvious ("backend repo") and add nothing.

<Note>
  The cross-repo pass looks for **mismatches across the boundary** — a field name, key, encoding, or status value on one side that doesn't match what the other side produces or expects. Linking a canonical library removes the blind spot (the agent can now read it), but it does not, by itself, make the review flag "a canonical implementation already exists and this PR re-implemented a weaker one". If you want that check, encode it as a [Kody Rule](/en/how_to_use/code_review/configs/kody_rules) and use the instruction to point at where the canonical implementations live.
</Note>

### Ref pin (branch selection)

Controls which branch ("ref") of the linked repository Kody reads. **Most teams leave this empty**: Kody then reads the branch with the same name as your PR's branch when it exists (so coordinated multi-repo changes see each other before merging), and falls back to the default branch otherwise.

The full resolution order, first match wins:

1. **PR description override** — mention the linked repo's branch or PR in the description of the PR under review (e.g. `org/backend-api#123` or `org/backend-api@feature-x`). One-off, highest priority. Only applies to repos already linked.
2. **Config `ref` pin** (this field), if set.
3. **Open PR on a matching branch** — an open pull request in the linked repo whose head branch matches your PR's head branch.
4. **Same branch name** in the linked repo.
5. The linked repo's **default branch** (then `main`/`master` as fallbacks).

Steps 3–4 are what keep multi-repo feature work aligned: the review sees the companion change *before* it merges, instead of a default branch that doesn't contain it yet.

Set a **ref pin** (e.g. `main`, `develop`, `release/2.x`) when you want deterministic reviews against a stable branch — for example, when branch names are reused across repos for unrelated work and the same-branch match would pick up the wrong thing. The PR description override still wins over the pin for one-off cases.

<Tip>
  For a submodule, pin `ref` to the commit or branch your repo actually tracks if it lags behind the library's default branch — otherwise the review may compare against code you haven't pulled yet.
</Tip>

The review summary always shows which ref was actually used. For a walkthrough with examples, see [How to use linked repositories](/en/knowledge_base/how-to-use-linked-repositories-in-code-review).