Skip to main content
Repositórios Vinculados permitem que o Kody leia outros repositórios da sua organização como contexto somente-leitura enquanto revisa um pull request. Sem isso, a revisão enxerga exatamente uma coisa: o repositório em revisão, no head do PR. Tudo que vive em outro repositório — um serviço que você chama, uma biblioteca que você importa, um git submodule — é invisível. Disponível nos planos Teams e Enterprise. Configurado por repositório — não existe padrão global, porque as relações são direcionais: vincular frontend → backend-api significa que revisões de frontend podem consultar backend-api, e não o contrário. Vincule as duas direções explicitamente se os dois times quiserem a verificação.

​
Quando você precisa disso

Três situações, todas comuns, todas invisíveis para uma revisão de repositório único:
  1. Quebra de contrato producer/consumer. O backend renomeia um campo da API e o frontend continua lendo o antigo; um producer adiciona um valor de enum que nenhum consumer trata; writer e reader derivam a mesma chave de cache de formas diferentes. O contrato está dividido em dois repositórios e não é garantido por nada.
  2. O código do qual seu repositório depende não está no seu repositório. Git submodules, pacotes internos vendorizados, bibliotecas compartilhadas baixadas no build. A revisão clona seu repositório sem submodules e sem instalar pacotes, então uma dependência via submodule ou de build é um diretório vazio (ou um import que o agente não consegue seguir) durante a revisão. Se seus tipos, regras ou clients canônicos vivem num repositório assim, vinculá-lo é a única forma de a revisão lê-los.
  3. A mesma regra de negócio reimplementada por canal ou serviço. Precificação, disponibilidade, validação, transições de estado de pedido que existem uma vez num lugar canônico e são copiadas, aproximadamente, em outros. Vincular o repositório canônico permite que o agente compare com a fonte da verdade em vez de chutar.
O que a revisão já enxerga sem essa feature: o repositório completo em revisão (não só o diff) no commit head do PR, mais a descrição do PR. Ela consegue fazer grep e ler qualquer arquivo desse checkout. Não consegue ver outros repositórios, conteúdo de submodules nem dependências instaladas.
Repositórios vinculados não cobrem contratos que vivem fora do seu código — as regras de validação de uma API de terceiros, por exemplo, não são descobríveis em nenhum repositório vinculado.

​
O que você ganha

Um exemplo concreto. Seu PR de frontend adiciona este tratamento de erro:
Com o backend vinculado, o Kody verifica o outro lado desse contrato e comenta no PR:
Bug · medium — [cross-repo] O frontend verifica error.response?.data?.error procurando INTEGRATION_NOT_APPROVED, mas o sendError do backend (src/api/response.ts) retorna o código num campo message. O branch de not-approved nunca casa, então os usuários sempre veem o toast de erro genérico. Leia data.message.
O resumo da revisão também mostra o que foi consultado: Additional context used: org/backend-api@main.

​
Onde os achados caem

  • Todo comentário cai numa linha do diff do seu PR. O código do repositório vinculado é citado dentro do comentário como evidência, com a tag [cross-repo] e o arquivo da contraparte nomeado. O Kody nunca comenta, registra achados nem modifica o repositório vinculado.
  • Achados só são levantados com evidência confirmada no arquivo da contraparte — “este literal precisa bater com o backend” sem prova não é emitido.
  • A linha Additional context used só aparece quando um repositório vinculado foi de fato lido durante a revisão. Sem a linha, ele não foi consultado (veja abaixo por que isso acontece).

​
Como funciona

Quando um pull request num repositório com repositórios vinculados toca superfície de fronteira, o agente de revisão do Kody pode buscar e ler os repositórios vinculados — do mesmo jeito que faz grep no seu próprio repositório — para verificar se os dois lados do contrato continuam de acordo. Os repositórios vinculados são baixados de forma preguiçosa, só quando o agente os lê pela primeira vez.

​
O que arma a passagem

Configurar um vínculo não basta por si só. Antes da revisão, uma checagem determinística e barata varre as linhas adicionadas do diff do PR e só habilita as ferramentas cross-repo quando encontra superfície de fronteira:
  • literais de string (códigos, nomes de evento, segmentos de path, nomes de header)
  • símbolos exportados (export function/const/class/type/interface/enum)
  • membros de enum, type ou interface
  • chaves de objeto / payload / DTO
  • identificadores com cara de status, estado ou código de erro (status, code, errorCode, kind, event, key, …)
  • paths com cara de contrato (dto/, schema/, api/, types/, clients/, openapi, proto, …)
Refatorações puramente internas — renomear um helper privado, mover código de lugar, formatação — normalmente não batem em nenhum desses, então os repositórios vinculados nunca são baixados e a revisão roda exatamente como uma revisão de repositório único. Isso é intencional: mantém a passagem desligada em diffs onde ela não encontraria nada.

​
Quando você não vê nada

Se um PR num repositório com repositórios vinculados não mostra a linha Additional context used, aconteceu uma destas coisas, em ordem aproximada de probabilidade:
  1. O diff não tinha superfície de fronteira (o gate ficou desligado — esperado em refatorações).
  2. O gate estava ligado, mas o agente não precisou do repositório vinculado para chegar às conclusões.
  3. O repositório vinculado não pôde ser baixado (permissões, timeout) — a revisão continua sem ele.
  4. O repositório vinculado não está conectado a esta organização Kodus, ou o plano da organização não inclui a feature — o vínculo é ignorado.
Os dois primeiros são a feature funcionando como projetado. Para confirmar que um vínculo está certo, abra um PR que de fato mude um literal compartilhado, um campo de DTO ou um tipo exportado — isso arma o gate e dá ao agente um motivo para olhar do outro lado.
  • Só podem ser vinculados repositórios já conectados à mesma organização Kodus (o Kody reaproveita sua integração de Git existente — sem tokens extras).
  • Até 3 repositórios vinculados por repositório.
  • O acesso é somente leitura. O Kody nunca faz push, comenta nem modifica um repositório vinculado.
  • Se um repositório vinculado não puder ser buscado (permissões, timeout), a revisão continua normalmente sem ele.

​
Adicionando um repositório vinculado

​
No app web

Vá em Code Review Settings → seu repositório → Linked Repositories, escolha um repositório da lista (só aparecem repositórios conectados) e salve. Cada vínculo tem dois campos opcionais, descritos abaixo.

​
No kodus-config.yml

linkedRepositories também é uma chave do arquivo de config, então os vínculos podem ficar versionados junto com o resto das suas configurações de revisão:
  • repository (obrigatório) — nome completo de um repositório conectado à organização (owner/repo).
  • instructions, ref — mesmo significado dos campos do app web (abaixo).
A interação do arquivo com as configurações da web segue as regras normais do arquivo de config: o arquivo só é lido quando kodusConfigFileOverridesWebPreferences está habilitado para o repositório (Settings → Code Review → o repositório → General), é lido do branch padrão do repositório, e a lista linkedRepositories do arquivo substitui a lista da web para aquele repositório (as listas não são mescladas; linkedRepositories: [] no arquivo desliga a feature). A exigência de plano vale independentemente de onde os vínculos são declarados.

​
Instruções

Uma dica em texto livre que diz ao agente de revisão para que serve esse vínculo e onde olhar. O Kody funciona sem ela, mas uma boa instrução deixa a passagem entre repositórios mais rápida e precisa — é a diferença entre o agente explorar o repositório vinculado do zero e ir direto ao código relevante. Boas instruções nomeiam a relação e os caminhos que sustentam o contrato:
Para uma biblioteca ou submodule vinculado (caso 2 acima), diga que o código não está neste repositório e contra o que o agente deve conferir:
Instruções fracas repetem o óbvio (“repositório do backend”) e não acrescentam nada.
A passagem cross-repo procura divergências na fronteira — um nome de campo, chave, encoding ou valor de status de um lado que não bate com o que o outro lado produz ou espera. Vincular uma biblioteca canônica remove o ponto cego (o agente passa a conseguir lê-la), mas não faz, por si só, a revisão apontar “já existe uma implementação canônica e este PR reimplementou uma versão mais fraca”. Se você quer essa checagem, codifique-a como uma Kody Rule e use a instrução para apontar onde vivem as implementações canônicas.

​
Ref pin (seleção de branch)

Controla qual branch (“ref”) do repositório vinculado o Kody lê. A maioria dos times deixa vazio: o Kody então lê a branch com o mesmo nome da branch do seu PR quando ela existe (para que mudanças coordenadas entre repositórios se enxerguem antes do merge), e cai na branch padrão caso contrário. A ordem completa de resolução, vence a primeira que casar:
  1. Override na descrição do PR — mencione a branch ou o PR do repositório vinculado na descrição do PR em revisão (ex.: org/backend-api#123 ou org/backend-api@feature-x). Pontual, prioridade máxima. Só vale para repositórios já vinculados.
  2. Pin de ref na config (este campo), se definido.
  3. PR aberto numa branch correspondente — um pull request aberto no repositório vinculado cuja head branch coincide com a head branch do seu PR.
  4. Mesmo nome de branch no repositório vinculado.
  5. A branch padrão do repositório vinculado (depois main/master como fallback).
Os passos 3–4 são o que mantém trabalho de feature multi-repo alinhado: a revisão vê a mudança companheira antes de ela ser mergeada, em vez de uma branch padrão que ainda não a contém. Defina um ref pin (ex.: main, develop, release/2.x) quando quiser revisões determinísticas contra uma branch estável — por exemplo, quando nomes de branch são reaproveitados entre repositórios para trabalhos não relacionados e o casamento por mesmo nome pegaria a coisa errada. O override na descrição do PR ainda vence o pin em casos pontuais.
Para um submodule, fixe o ref no commit ou branch que seu repositório realmente acompanha se ele estiver atrás do branch padrão da biblioteca — senão a revisão pode comparar com código que você ainda não puxou.
O resumo da revisão sempre mostra qual ref foi realmente usado. Para um passo a passo com exemplos, veja Como usar repositórios vinculados.