Conectar repositórios do GitHub Enterprise Cloud ao agente Azure SRE

Importante

Esse recurso de Azure Agente SRE está atualmente em versão prévia. Veja os Termos de Uso Complementares para Versões Prévias do Microsoft Azure para obter termos legais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.

Conecte repositórios hospedados no GitHub Enterprise Cloud (<TENANT>.ghe.com) ou github.com ao agente SRE do Azure usando um aplicativo GitHub BYO (Bring Your Own). O agente gera tokens de instalação de curta duração a partir da chave privada da sua aplicação, que é armazenada no Azure Key Vault e nunca é copiada.

Note

O aplicativo GitHub BYO funciona para hosts github.com e *.ghe.com. Para github.com com OAuth ou PAT, consulte Configurar o conector do GitHub.

Quando usar a autenticação de aplicativo GitHub BYO

Use o aplicativo BYO quando:

  • Sua organização requer autenticação baseada em aplicativo e controles de custódia de chave.
  • Você está conectando repositórios *.ghe.com (necessários porque OAuth e PAT não estão disponíveis para hosts GHE).
  • Você deseja acesso baseado em token de instalação em vez de tokens de usuário.

Pré-requisitos

Requirement Detalhes
Agente SRE do Azure Um agente em estado de execução com a função administrador ou usuário padrão
Aplicativo GitHub Um aplicativo GitHub criado no host de destino (github.com ou <TENANT>.ghe.com)
GitHub acesso de administrador Acesso de administrador da organização ou do repositório para criar, instalar ou verificar o escopo do GitHub App
Azure Key Vault Um cofre onde você pode armazenar a chave privada do aplicativo GitHub
Identidade gerenciada Capacidade de atribuir Usuário de Criptografia do Key Vault na chave importada à identidade usada pelo agente

Criar um aplicativo GitHub

Se você já tiver um Aplicativo do GitHub com as permissões corretas, pule para Armazene a chave privada no Azure Key Vault.

  1. Vá para o host GitHub:
    • github.com: vá para sua organização >Settings>Developer settings>GitHub Apps>New GitHub App
    • <TENANT>.ghe.com: mesmo caminho em sua instância do GHE
  2. Preencha os detalhes do aplicativo:
    • GitHub Nome do aplicativo: por exemplo, sre-agent-reader
    • URL da home page: https://sre.azure.com
    • Webhook: Desmarque Ativo (o agente não usa webhooks)
  3. Em Permissões, defina:
    • Permissões > de repositório Conteúdo: Somente leitura (obrigatório)
    • Permissões > de repositório Metadados: somente leitura (selecionado automaticamente)
    • Opcionalmente, adicione acesso de leitura a Problemas e Solicitação de pull
  4. Em Onde este GitHub App pode ser instalado?, selecione Somente nesta conta.
  5. Selecione Criar Aplicativo do GitHub.
  6. Observe a ID do cliente mostrada na página de configurações do aplicativo.

Instalar a aplicação GitHub

  1. Na página de configurações do aplicativo GitHub, selecione Instalar Aplicativo na barra lateral esquerda.
  2. Selecione sua organização.
  3. Selecione Todos os repositórios ou selecione repositórios específicos.
  4. Selecione Instalar.

Gerar uma chave privada do aplicativo GitHub

  1. Na página de configurações do aplicativo GitHub, role até Private keys.
  2. Selecione Gerar uma chave privada.
  3. Um .pem arquivo é baixado. Esse arquivo é a chave privada RSA que o agente usa para autenticar.

Caution

Mantenha o PEM seguro. Carregue-o para Key Vault na próxima etapa. Não o confirme em um repositório e não compartilhe-o.

Armazene a chave privada no Azure Key Vault

Importe a chave privada do GitHub App como uma chave RSA, não como um segredo, com a operação Sign ativada. Converta o PEM baixado do GitHub para PKCS#8 antes da importação, depois delete permanentemente os arquivos PEM locais após uma importação bem-sucedida. Para os comandos, veja Armazenar chave privada no Key Vault.

Copie o URI do Identificador de Chave da chave importada:

https://myvault.vault.azure.net/keys/my-github-app-key/<VERSION>

Dica

URI com versão vs. sem versão: Você pode usar a URI com versão (com o sufixo /<VERSION>) para fixar em uma versão específica da chave ou omitir a versão para sempre usar a versão mais recente. Use o URI sem versão para que, quando você rotacionar a chave, o agente passe a usar automaticamente a nova versão sem atualizar o URI.

Conceder acesso de identidade de agente ao Key Vault

  1. No portal do Azure, abra Key Vault>Access control (IAM).
  2. Atribua Key Vault Crypto User à identidade selecionada para acesso ao Key Vault. Limite a atribuição à chave importada, ou apenas ao cofre se for dedicado a este app.
  3. Aguarde até que a atribuição de função entre em vigor.

Configurar o aplicativo BYO no acesso ao código

  1. Abra seu agente no portal.
  2. Vá para Construir + configurar>Contexto>.
  3. Selecione Adicionar repositório.
  4. Na etapa Conexão, escolha GitHub e insira uma URL completa do repositório, como https://<TENANT>.ghe.com/owner/repo.
  5. Se existir uma credencial correspondente, escolha Nova conexão em Adicionar repositório com para configurar outra credencial.
  6. Em Método de conexão, selecione Use your GitHub App.
  7. Entrar:
    • ID do cliente
    • URI de chave privada (Key Vault): um /keys/ URI, não um /secrets/ URI
    • Identidade do Key Vault opcional (ou manter a atribuída pelo sistema)
  8. Selecione Conectar.

O assistente valida suas credenciais. Se tudo der certo, você verá Conectado como Aplicativo GitHub com uma marca de verificação verde.

Note

Quando a URL do repositório usa um host *.ghe.com, o assistente seleciona Usar seu GitHub App. O OAuth e o PAT não estão disponíveis para hosts GHE.

Adicionar repositórios e verificar a conexão

  1. Selecione Próximo para abrir Adicionar repositórios, revise as entradas do repositório e os nomes de exibição, e selecione Salvar.
  2. Confirme que o repositório aparece na lista de acesso ao código com sua conexão na coluna Conexão .
  3. Teste no chat:
Get me recent issues from owner/repo.

Identidade gerenciada por aplicativo para vários aplicativos do GitHub

Por padrão, o agente usa sua identidade gerenciada atribuída ao sistema para operações de assinatura do Key Vault. Se você gerencia vários GitHub Apps (por exemplo, um por instância do GHE), pode atribuir uma identidade gerenciada atribuída ao usuário diferente a cada app. Cada identidade precisa de acesso apenas à sua própria chave do Key Vault.

Selecione a identidade na lista suspensa identidade do Key Vault na etapa de configuração.

Suporte a múltiplos hosts para conexões com o GitHub

Você pode conectar vários hosts GitHub ao mesmo agente. Cada host tem autenticação independente:

  • github.com → aplicativo OAuth, PAT ou BYO
  • contoso.ghe.com → aplicativo BYO
  • engineering.ghe.com → aplicativo BYO (com um aplicativo GitHub diferente)

Desconectar um host não afeta outras pessoas.

Troubleshooting

Sintoma Causa provável Corrigir
Falha na validação de autenticação ID do cliente incorreta ou host incorreto Verifique se o aplicativo foi criado no mesmo host informado no Code Access.
Falha ao assinar com o Key Vault URI da chave incorreta ou permissões da chave ausentes Use um URI RSA /keys/ com Assinatura habilitada e conceda o Usuário de Criptografia do Key Vault à identidade selecionada.
O repositório aparece como com falha em Acesso ao código Permissões do aplicativo ou escopo de instalação ausentes Verifique Metadados: leitura + Conteúdo: leitura e escopo de instalação.
Problemas de chat funcionam, mas o Acesso ao Código falha As verificações de endpoint/caminho são diferentes Execute novamente o teste de conexão e verifique a permissão de metadados.

Próxima etapa