Como configurar os filtros de contexto do Sourcegraph Cody para excluir repositórios confidenciais do contexto de IA

Durante a adoção do assistente de codificação com inteligência artificial Sourcegraph Cody em ambientes corporativos, líderes de engenharia e equipes de segurança e conformidade (compliance) enfrentam uma preocupação crítica de governança: como garantir que algoritmos proprietários, segredos comerciais ou bases de código sujeitas a exigências regulatórias rigorosas (como PCI-DSS, HIPAA ou ITAR) nunca sejam transmitidos como contexto para modelos de linguagem ampla (LLMs) de terceiros?

O Sourcegraph Cody oferece um recurso corporativo centralizado e obrigatório no servidor denominado filtros de contexto (cody.contextFilters). Configurado diretamente na Configuração do Site (Site Configuration) do Sourcegraph, ele permite que administradores definam políticas de inclusão e exclusão utilizando expressões regulares RE2. Essas regras determinam com precisão quais repositórios o Cody pode acessar para gerar sugestões de autocompletar, respostas no chat e execuções de comandos.

Este guia orienta os administradores na configuração do cody.contextFilters, explica a lógica de precedência e a sintaxe de expressões regulares e apresenta as melhores práticas para uma defesa em profundidade da privacidade do código-fonte.

Pré-requisitos e compatibilidade de clientes

Antes de habilitar os filtros de contexto, certifique-se de que sua infraestrutura e os ambientes dos desenvolvedores atendam aos seguintes critérios:

• Instância do Sourcegraph: Versão Sourcegraph Enterprise 5.4.0 ou superior com licença ativa do Cody Enterprise.
• Feature Flag: A chave cody-context-filters-enabled deve estar definida como true.
• Clientes IDE compatíveis:
  • Extensão para VS Code: versão >= 1.20.0.
  • Plugin para JetBrains: versão >= 6.0.0.
  • Cliente Web do Sourcegraph.

Matriz de compatibilidade e aplicação de políticas

Para evitar que desenvolvedores burlem as políticas de conformidade utilizando versões antigas de extensões em seus editores, o servidor Sourcegraph aplica regras de compatibilidade retroativa:

Nas versões modernas do Sourcegraph, clientes legados incapazes de processar diretivas de filtros de contexto têm o envio de contexto imediatamente bloqueado e são orientados a atualizar suas extensões.

Estrutura de configuração e sintaxe RE2

Os filtros de contexto são configurados no JSON de Configuração do Site do Sourcegraph sob a chave cody.contextFilters. O esquema aceita duas listas opcionais: include (repositórios permitidos) e exclude (repositórios bloqueados).

{
  "cody.contextFilters": {
    "include": [
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/.*"
      }
    ],
    "exclude": [
      {
        "repoNamePattern": ".*-sensitive$"
      },
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/core-payments.*"
      }
    ]
  }
}

Regras fundamentais do esquema:

• Se cody.contextFilters for declarado, ele deve conter ao menos um bloco (include ou exclude).
• Cada elemento das listas consiste em um objeto contendo a propriedade obrigatória repoNamePattern.
• O padrão repoNamePattern deve seguir a sintaxe de expressões regulares RE2 (motor implementado em Go).
• No formato JSON, barras invertidas devem ser escapadas com barra dupla (\\). Um ponto literal deve ser escrito como \\., e barras normais podem ser escapadas como \\/ ou escritas diretamente como /.
• O padrão é avaliado em relação ao nome canônico completo do repositório cadastrado no Sourcegraph (por exemplo, github.com/organizacao/repositorio ou caminhos internos do GitLab).

Lógica de avaliação e precedência de regras

O comportamento do Cody varia de acordo com a combinação das regras de inclusão e exclusão:

1. Filtro não definido (comportamento padrão)

Se o campo cody.contextFilters for omitido, o Cody opera sob o modelo de permissões padrão, acessando o contexto de qualquer repositório no qual o desenvolvedor tenha privilégio de leitura no Sourcegraph.

2. Apenas regras de include definidas (Lista de permissões estrita)

O Cody só pode buscar contexto de repositórios cujo nome coincida com ao menos um padrão listado em include. Todos os demais repositórios são bloqueados por padrão.

• Recomendado para organizações que adotam uma estratégia de Zero-Trust para IA, liberando o uso apenas para bibliotecas e serviços de baixo risco previamente homologados.
• Basta uma única correspondência na lista include para que o repositório seja autorizado.

{
  "cody.contextFilters": {
    "include": [
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/frontend-.*"
      },
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/public-docs$"
      }
    ]
  }
}

3. Apenas regras de exclude definidas (Lista de bloqueio)

O Cody pode acessar o contexto de qualquer repositório, exceto daqueles cujos nomes correspondam a ao menos um padrão em exclude.

• Recomendado para corporações que desejam disponibilizar o Cody em larga escala para impulsionar a agilidade de desenvolvimento, mantendo protegidos repositórios críticos (como mecanismos de liquidação financeira, chaves criptográficas ou núcleos antifraude).
• Definir .* em exclude funciona como um botão de parada emergencial (kill-switch), bloqueando todo o acesso a contexto na instância.

{
  "cody.contextFilters": {
    "exclude": [
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/crypto-vault$"
      },
      {
        "repoNamePattern": ".*payment-processing.*"
      },
      {
        "repoNamePattern": ".*-restricted$"
      }
    ]
  }
}

4. Ambas as regras include e exclude definidas (Filtragem combinada)

Quando ambos os blocos estão presentes, o repositório precisa atender a duas condições simultaneamente:

1. Coincidir com ao menos um padrão em include.
2. Não coincidir com nenhum padrão em exclude.

Regras de exclusão sempre têm prioridade sobre regras de inclusão. No exemplo a seguir, todos os repositórios da example-corp são autorizados, exceto aqueles que contenham compliance no nome ou terminem com -secret:

{
  "cody.contextFilters": {
    "include": [
      {
        "repoNamePattern": "^github\\.com\\/example-corp\\/.+"
      }
    ],
    "exclude": [
      {
        "repoNamePattern": ".*compliance.*"
      },
      {
        "repoNamePattern": ".*-secret$"
      }
    ]
  }
}

Passo a passo de configuração para administradores

Siga estas etapas para aplicar e validar as restrições em sua instância Sourcegraph:

Passo 1: Auditar os nomes de repositórios no Sourcegraph

O Cody avalia os padrões contra o nome completo registrado no banco de dados do Sourcegraph.

• Acesse o console web do Sourcegraph e vá em Site Admin > Repositories.
• Verifique as convenções de caminho (ex.: github.com/sua-empresa/... ou domínios de GitLab corporativo).
• Mapeie os repositórios classificados como confidenciais ou restritos por compliance.

Passo 2: Acessar a Configuração do Site

1. Faça login no Sourcegraph com credenciais de administrador (Site Admin).
2. Clique no avatar do usuário no canto superior direito e selecione Site Admin.
3. No menu lateral esquerdo, clique em Configuration (no caminho /site-admin/configuration).

Passo 3: Inserir a configuração de cody.contextFilters

Adicione as diretivas desejadas dentro do objeto JSON principal:

{
  // ... outras configurações do site ...
  "cody-context-filters-enabled": true,
  "cody.contextFilters": {
    "include": [
      {
        "repoNamePattern": "^github\\.com\\/sua-empresa\\/.*"
      }
    ],
    "exclude": [
      {
        "repoNamePattern": "^github\\.com\\/sua-empresa\\/core-financeiro$"
      },
      {
        "repoNamePattern": ".*proprietary.*"
      },
      {
        "repoNamePattern": ".*sec-tools.*"
      }
    ]
  }
}

Passo 4: Salvar e aplicar

Clique no botão Save changes ao final da página. O Sourcegraph atualiza as configurações em tempo real, sem necessidade de reiniciar a instância ou contêineres.

Passo 5: Validar nos ambientes de desenvolvimento

Verifique se a política está sendo respeitada diretamente nos IDEs:

1. Abra um projeto pertencente a um repositório excluído no VS Code ou JetBrains.
2. Tente executar uma edição inline (Edit) ou acionar a geração de código. O plugin cancelará o envio e exibirá a mensagem de erro:

   Edit failed to run: file is ignored (due to cody.contextFilters Enterprise configuration setting)
   

3. Na janela do Cody Chat, tente mencionar arquivos ou símbolos do repositório restrito via @-mention. Confirme que eles não aparecem na lista de sugestões de contexto e que o Cody não extrai fragmentos de código dessa base.

Experiência do desenvolvedor e funcionalidades afetadas

Compreender o impacto prático no dia a dia dos engenheiros auxilia em uma comunicação transparente:

• Chat genérico preservado: Mesmo ao trabalhar em um projeto excluído, o desenvolvedor pode usar o chat do Cody para tirar dúvidas de sintaxe, compreender conceitos teóricos ou depurar trechos isolados de código. O arquivo do repositório sensível simplesmente não é anexado ao prompt.
• Restrição de prompts avançados: Recursos que dependem do contexto estrutural completo do repositório (como Prompts corporativos customizados) podem apresentar falhas ou ser desativados em projetos excluídos.
• Bloqueio de autocompletar: Se o arquivo ativo fizer parte de um repositório excluído, o Cody suspende o envio de trechos locais para os servidores do LLM, garantindo proteção em tempo real.

Modelo de governança em camadas: Comparativo de segurança

A governança corporativa de código-fonte é mais robusta quando estruturada em camadas complementares de controle:

Ao adotar o cody.contextFilters no nível central, utilizar .cody/ignore para credenciais locais de desenvolvimento e apoiar-se nos acordos de retenção zero do Cody Gateway, as empresas criam um perímetro seguro para alavancar a produtividade de engenharia sem colocar em risco seus maiores ativos intelectuais.

Referências

• Manage Cody Context - Sourcegraph docs
• Cody Enterprise features - Sourcegraph docs
• Cody FAQs - Sourcegraph docs