Skip to main content
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.
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.
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:
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.
  • 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.

​
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:
  • 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: 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:
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:
Las instrucciones débiles repiten lo obvio (“repositorio del backend”) y no aportan nada.
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 y usa la instrucción para indicar dónde viven las implementaciones canónicas.

​
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.
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.
El resumen de la revisión siempre muestra qué ref se usó realmente. Para un recorrido con ejemplos, consulta Cómo usar repositorios vinculados.