> ## 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 to catch cross-repo contract mismatches during review.

Linked Repositories let Kody read sibling repositories as **read-only context** while reviewing a pull request. Use it to catch the bugs a single-repo review can't see: the backend renames an API field and the frontend still reads the old one, a producer adds an enum value no consumer handles, or writer and reader derive the same key differently.

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.

## 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** — The frontend checks `error.response?.data?.error` for `INTEGRATION_NOT_APPROVED`, but the backend's `sendError` 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`.

## How it works

When a pull request in a repository with linked repositories touches boundary surface (changed string literals, payload fields, status values, exported symbols), 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. Findings are only raised with confirmed evidence from the counterpart file, and the comment always lands on a line of **your** PR; linked-repo code is quoted inside it as supporting evidence, never commented on directly.

Reviews that used cross-repo context say so: the review summary includes an
**Additional context used** line listing each repository and the ref it was
read at.

<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

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.

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

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

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

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

## When to use it

Linked repositories pay off when repositories share a contract that isn't enforced by tooling:

* **Frontend ↔ backend** pairs that re-declare payload shapes on each side.
* **Service ↔ service** integrations passing status values, event names, or IDs.
* **Consumers of a shared library** that re-implement or mirror its types.

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