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

# Repositorios Vinculados

> Deja que Kody lea repositorios hermanos como contexto durante la revisión — para contratos entre repositorios y para código del que tu repositorio depende pero no contiene.

Los Repositorios Vinculados permiten que Kody lea otros repositorios de tu organización como **contexto de solo lectura** mientras revisa un pull request. Sin esto, la revisión ve exactamente una cosa: el repositorio en revisión, en el head del PR. Todo lo que vive en otro repositorio — un servicio que llamas, una librería que importas, un git submodule — es invisible.

Disponible en los planes **Teams y Enterprise**. Se configura **por repositorio** — no hay valor global por defecto, porque las relaciones son direccionales: vincular `frontend → backend-api` significa que *las revisiones de `frontend`* pueden consultar `backend-api`, no al revés. Vincula ambas direcciones explícitamente si los dos equipos quieren la comprobación.

## Cuándo lo necesitas

Tres situaciones, todas comunes, todas invisibles para una revisión de un solo repositorio:

1. **Rotura de contrato producer/consumer.** El backend renombra un campo de la API y el frontend sigue leyendo el anterior; un producer añade un valor de enum que ningún consumer maneja; writer y reader derivan la misma clave de caché de forma distinta. El contrato está repartido entre dos repositorios y nada lo garantiza.

2. **El código del que depende tu repositorio no está en tu repositorio.** Git submodules, paquetes internos vendorizados, librerías compartidas descargadas en el build. La revisión clona tu repositorio *sin submodules* y *sin instalar paquetes*, así que una dependencia por submodule o de build es un directorio vacío (o un import que el agente no puede seguir) durante la revisión. Si tus tipos, reglas o clients canónicos viven en un repositorio así, vincularlo es la única forma de que la revisión los lea.

3. **La misma regla de negocio reimplementada por canal o servicio.** Precios, disponibilidad, validación, transiciones de estado de pedido que existen una vez en un lugar canónico y se copian, aproximadamente, en otros. Vincular el repositorio canónico permite que el agente compare contra la fuente de verdad en lugar de adivinar.

<Note>
  **Lo que la revisión ya ve sin esta función:** el repositorio completo en revisión (no solo el diff) en el commit head del PR, más la descripción del PR. Puede hacer grep y leer cualquier archivo de ese checkout. No puede ver otros repositorios, el contenido de submodules ni dependencias instaladas.
</Note>

Los repositorios vinculados **no** cubren contratos que viven fuera de tu código — las reglas de validación de una API de terceros, por ejemplo, no son descubribles en ningún repositorio vinculado.

## Qué obtienes

Un ejemplo concreto. Tu PR de frontend añade este manejo de errores:

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

Con el backend vinculado, Kody comprueba el otro lado de ese contrato y comenta en el PR:

> **Bug · medium** — \[cross-repo] El frontend comprueba `error.response?.data?.error` buscando `INTEGRATION_NOT_APPROVED`, pero el `sendError` del backend (`src/api/response.ts`) devuelve el código en un campo `message`. La rama de not-approved nunca coincide, así que los usuarios siempre ven el toast de error genérico. Lee `data.message` en su lugar.

El resumen de la revisión también muestra qué se consultó: **Additional context used:** `org/backend-api@main`.

### Dónde aterrizan los hallazgos

* Cada comentario aterriza en una línea del **diff de tu PR**. El código del repositorio vinculado se cita dentro del comentario como evidencia, etiquetado `[cross-repo]`, con el archivo de la contraparte nombrado. Kody nunca comenta, registra hallazgos ni modifica el repositorio vinculado.
* Los hallazgos solo se plantean con evidencia confirmada en el archivo de la contraparte — "este literal debe coincidir con el backend" sin prueba no se emite.
* La línea **Additional context used** aparece solo cuando un repositorio vinculado se leyó realmente durante la revisión. Si no hay línea, no se consultó (más abajo explicamos por qué ocurre).

## Cómo funciona

Cuando un pull request en un repositorio con repositorios vinculados toca superficie de frontera, el agente de revisión de Kody puede buscar y leer los repositorios vinculados — igual que hace grep en tu propio repositorio — para verificar que ambos lados del contrato siguen de acuerdo. Los repositorios vinculados se obtienen de forma perezosa, solo cuando el agente los lee por primera vez.

### Qué activa la pasada

Configurar un vínculo no basta por sí solo. Antes de la revisión, una comprobación determinista y barata recorre las **líneas añadidas** del diff del PR y habilita las herramientas cross-repo solo cuando encuentra *superficie de frontera*:

* literales de cadena (códigos, nombres de evento, segmentos de ruta, nombres de header)
* símbolos exportados (`export function/const/class/type/interface/enum`)
* miembros de enum, type o interface
* claves de objeto / payload / DTO
* identificadores con pinta de estado, status o código de error (`status`, `code`, `errorCode`, `kind`, `event`, `key`, …)
* rutas de archivo con pinta de contrato (`dto/`, `schema/`, `api/`, `types/`, `clients/`, `openapi`, `proto`, …)

Las refactorizaciones puramente internas — renombrar un helper privado, mover código, formatear — normalmente no tocan nada de esto, así que los repositorios vinculados nunca se obtienen y la revisión corre exactamente como una revisión de un solo repositorio. Es intencional: mantiene la pasada apagada en diffs donde no encontraría nada.

### Cuando no ves nada

Si un PR en un repositorio con repositorios vinculados **no** muestra la línea `Additional context used`, ocurrió una de estas cosas, en orden aproximado de probabilidad:

1. El diff no tenía superficie de frontera (el gate se quedó apagado — esperable en refactorizaciones).
2. El gate estaba encendido, pero el agente no necesitó el repositorio vinculado para llegar a sus conclusiones.
3. El repositorio vinculado no se pudo obtener (permisos, timeout) — la revisión continúa sin él.
4. El repositorio vinculado no está conectado a esta organización de Kodus, o el plan de la organización no incluye la función — el vínculo se ignora.

Los dos primeros son la función funcionando como está diseñada. Para confirmar que un vínculo está bien configurado, abre un PR que *sí* cambie un literal compartido, un campo de DTO o un tipo exportado — eso activa el gate y le da al agente una razón para mirar al otro lado.

<Info>
  * Solo se pueden vincular repositorios **ya conectados a la misma organización de Kodus** (Kody reutiliza tu integración de Git existente — sin tokens adicionales).
  * Hasta **3 repositorios vinculados** por repositorio.
  * El acceso es de solo lectura. Kody nunca hace push, comenta ni modifica un repositorio vinculado.
  * Si un repositorio vinculado no se puede obtener (permisos, timeout), la revisión continúa normalmente sin él.
</Info>

## Añadir un repositorio vinculado

### En la app web

Ve a **Code Review Settings → *tu repositorio* → Linked Repositories**, elige un repositorio de la lista (solo aparecen los conectados) y guarda. Cada vínculo tiene dos campos opcionales, descritos abajo.

### En `kodus-config.yml`

`linkedRepositories` también es una clave del archivo de configuración, así que los vínculos pueden vivir versionados junto al resto de tu configuración de revisión:

```yaml theme={null}
linkedRepositories:
  - repository: "org/backend-api"
    instructions: "API REST que consume este frontend"
    ref: main   # pin opcional; omítelo para la cascada de misma rama
```

* `repository` (obligatorio) — nombre completo de un repositorio conectado a la organización (`owner/repo`).
* `instructions`, `ref` — mismo significado que los campos de la app web (abajo).

La interacción del archivo con la configuración web sigue las [reglas normales del archivo de configuración](/es/how_to_use/code_review/configs/general#prioridad-de-configuración): el archivo solo se lee cuando `kodusConfigFileOverridesWebPreferences` está habilitado para el repositorio (**Settings → Code Review → el repositorio → General**), se lee desde la **rama por defecto** del repositorio, y la lista `linkedRepositories` del archivo **reemplaza** la lista web de ese repositorio (las listas no se fusionan; `linkedRepositories: []` en el archivo apaga la función). El requisito de plan aplica sin importar dónde se declaren los vínculos.

### Instrucciones

Una pista en texto libre que le dice al agente de revisión **para qué sirve este vínculo y dónde mirar**. Kody funciona sin ella, pero una buena instrucción hace la pasada entre repositorios más rápida y precisa — es la diferencia entre que el agente explore el repositorio vinculado desde cero o vaya directo al código relevante.

Las buenas instrucciones nombran la relación y las rutas que sostienen el contrato:

```text theme={null}
API REST que consume este dashboard. Las respuestas de error las construye
src/api/response.ts — contrasta los códigos de error contra ese archivo.
```

```text theme={null}
Máquina de estados de pedido compartida. Los enums de estado viven en
src/domain/order-status.ts; debemos manejar todos los valores que define.
```

Para una librería o submodule vinculado (caso 2 de arriba), di que el código *no* está en este repositorio y contra qué debe comprobar el agente:

```text theme={null}
Librería canónica de reglas de negocio, tipos y clients. Se consume aquí como
git submodule, así que su código fuente no está en este repositorio. Las reglas
de validación viven en src/rules/, los clients de API en src/clients/ —
contrasta nombres de campo y valores de estado contra ellos.
```

Las instrucciones débiles repiten lo obvio ("repositorio del backend") y no aportan nada.

<Note>
  La pasada cross-repo busca **desajustes en la frontera** — un nombre de campo, clave, codificación o valor de estado de un lado que no coincide con lo que el otro lado produce o espera. Vincular una librería canónica elimina el punto ciego (el agente ya puede leerla), pero no hace, por sí solo, que la revisión señale "ya existe una implementación canónica y este PR reimplementó una versión más débil". Si quieres esa comprobación, codifícala como una [Kody Rule](/es/how_to_use/code_review/configs/kody_rules) y usa la instrucción para indicar dónde viven las implementaciones canónicas.
</Note>

### Ref pin (selección de rama)

Controla qué rama ("ref") del repositorio vinculado lee Kody. **La mayoría de los equipos lo deja vacío**: Kody entonces lee la rama con el mismo nombre que la de tu PR cuando existe (para que los cambios coordinados entre repositorios se vean antes del merge), y recurre a la rama por defecto en caso contrario.

El orden completo de resolución, gana la primera coincidencia:

1. **Override en la descripción del PR** — menciona la rama o el PR del repositorio vinculado en la descripción del PR en revisión (p. ej. `org/backend-api#123` o `org/backend-api@feature-x`). Puntual, máxima prioridad. Solo aplica a repositorios ya vinculados.
2. **Pin de `ref` en la configuración** (este campo), si está definido.
3. **PR abierto en una rama coincidente** — un pull request abierto en el repositorio vinculado cuya head branch coincide con la de tu PR.
4. **Mismo nombre de rama** en el repositorio vinculado.
5. La **rama por defecto** del repositorio vinculado (luego `main`/`master` como alternativas).

Los pasos 3–4 son lo que mantiene alineado el trabajo de features multi-repo: la revisión ve el cambio acompañante *antes* de que se fusione, en lugar de una rama por defecto que todavía no lo contiene.

Define un **ref pin** (p. ej. `main`, `develop`, `release/2.x`) cuando quieras revisiones deterministas contra una rama estable — por ejemplo, cuando los nombres de rama se reutilizan entre repositorios para trabajos no relacionados y la coincidencia por mismo nombre elegiría lo incorrecto. El override en la descripción del PR sigue ganando al pin en casos puntuales.

<Tip>
  Para un submodule, fija el `ref` al commit o rama que tu repositorio realmente sigue si va por detrás de la rama por defecto de la librería — de lo contrario la revisión puede comparar contra código que todavía no has traído.
</Tip>

El resumen de la revisión siempre muestra qué ref se usó realmente. Para un recorrido con ejemplos, consulta [Cómo usar repositorios vinculados](/es/knowledge_base/how-to-use-linked-repositories-in-code-review).