Configurar o conector BYO de aplicativo do GitHub no Azure SRE Agent

Conecte seu agente ao GitHub usando um Aplicativo Bring Your Own GitHub, uma identidade de serviço que sua organização registra com credenciais apoiadas por Key Vault.

Importante

Este tutorial configura o acesso baseado em aplicativo aos seus repositórios de GitHub usando um aplicativo GitHub BYO com credenciais com suporte Key Vault. Todas as operações são atribuídas à identidade do aplicativo, não a um usuário individual.

Quando usar o aplicativo BYO

Use o aplicativo BYO quando:

  • Sua organização requer autenticação baseada em aplicativo e controles de custódia de chave.
  • Você está se conectando a *.ghe.com repositórios (obrigatório).
  • Você deseja acesso baseado em token de instalação em vez de tokens de usuário.

Prerequisites

  • Agente em execução com a função administrador ou usuário padrão
  • Um aplicativo GitHub criado no host de destino (github.com ou *.ghe.com)
  • Acesso de administrador à organização ou ao repositório no GitHub (para criar, instalar ou verificar o escopo do GitHub App)
  • Chave privada do aplicativo armazenada em Azure Key Vault como um segredo
  • Identidade gerenciada do agente com a função Usuário de Segredos do Key Vault naquele cofre

Etapa 1: Criar um aplicativo GitHub

Se você já tiver um aplicativo GitHub com as permissões certas, vá para a Etapa 2.

  1. Vá para o host GitHub:
    • github.com: Vá para sua organização e selecione Configurações>Configurações do desenvolvedor>Aplicativos GitHub>Novo aplicativo GitHub.
    • <tenant>.ghe.com: mesmo caminho em sua instância do GHE.
  2. Preencha os detalhes do aplicativo:
    • GitHub Nome do aplicativo: por exemplo, contoso-sre-agent-reader (prefixo com o nome da organização para evitar conflitos).
    • 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 (começa com Iv..., isso é diferente da ID do aplicativo numérico).

Instalar o Aplicativo GitHub

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

Etapa 2: Gerar uma chave privada

  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.

Warning

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

Etapa 3: Armazenar chave privada no Key Vault

  1. Abra o portal Azure e vá para o Key Vault.
  2. Vá paraGeração/Importação de>.
  3. Defina o Nome (por exemplo sre-agent-github-app-key) e cole o conteúdo completo do PEM como o Valor (incluindo -----BEGIN RSA PRIVATE KEY----- e -----END RSA PRIVATE KEY----- cabeçalhos).
  4. Selecione Criar.
  5. Abra o segredo, selecione a versão atual e copie o URI do Identificador de Segredo :
https://myvault.vault.azure.net/secrets/my-github-app-key/<version>

Dica

Use o URI versionado (com o sufixo /<version>) para fixar em uma versão específica da chave, ou omita a versão para sempre usar a versão mais recente. Sem versionamento é recomendado. Quando você gira a chave, o agente automaticamente pega a nova versão sem atualizar o URI.

Etapa 4: Conceder acesso Key Vault à identidade do agente

  1. No portal Azure, abra o Key Vault e acesse o controle de acesso (IAM).
  2. Atribua Key Vault Secrets User à identidade gerenciada do agente.
  3. Aguarde a propagação da atribuição de função.

Etapa 5: Configurar o aplicativo BYO no Acesso ao Código

  1. Abra seu agente.
  2. Acesse Builder>Acesso ao código.

Captura de tela da página de Acesso ao Código na navegação Builder do Agente SRE do Azure.

  1. Selecione Adicionar repositórios.

  2. Escolha GitHub e insira o host:

    • github.com para o GitHub público.
    • <tenant>.ghe.com para Enterprise Cloud.
  3. Continue para Autenticação.

  4. Selecione Abring seu próprio aplicativo GitHub.

    Captura de tela do formulário de autenticação do BYO GitHub App, mostrando os campos ID do cliente e URI do Key Vault.

  5. Inserir:

    • ID do cliente
    • URI do segredo da chave privada (Key Vault)
    • Identidade do Key Vault opcional (ou manter a atribuída pelo sistema)
  6. Selecione Conectar.

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

Captura de tela do status de sucesso de

Note

Se você vir a marca de verificação verde e Conectado como GitHub App, suas credenciais são válidas. Se o Connect falhar, verifique sua ID do cliente, Key Vault URI e permissões de identidade gerenciada.

Se Acesso ao código não abrir pela navegação à esquerda, atualize a página do agente, expanda Builder novamente e tente de novo.

Importante

Quando você digita um domínio *.ghe.com como host, o assistente seleciona automaticamente Traga seu próprio aplicativo do GitHub. O OAuth e o PAT não estão disponíveis para hosts GHE.

Etapa 6: Adicionar repositórios e verificar

  1. Selecione repositórios e salve.

    Captura de tela da etapa de seleção do repositório mostrando os repositórios disponíveis a serem adicionados.

  2. Confirme se o cartão Acesso ao Código mostra o host conectado e o tipo de autenticação GitHubApp.

    Captura de tela da página de acesso ao código mostrando o host GitHub conectado com o tipo de autenticação gitHubApp.

  3. Testar o acesso ao código no chat:

What files are in the root of owner/repo?

Se você também tiver concedido permissão problemas ao seu aplicativo GitHub, verifique as operações de problema:

List recent issues from owner/repo.

Identidade gerenciada por aplicativo

Por padrão, o agente usa sua identidade gerenciada atribuída sistema para ler a chave privada de Key Vault. Se você gerenciar vários aplicativos GitHub (por exemplo, um por instância de GHE), atribua uma identidade gerenciada atribuída pelo usuário diferente a cada aplicativo. Essa abordagem fornece isolamento de segurança porque cada identidade só tem acesso ao seu próprio segredo Key Vault.

Selecione a identidade na lista suspensa Identidade do Key Vault na Etapa 5.

Suporte a vários hosts para conectores do 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 de GitHub diferente)

Desconectar um host não afeta outras pessoas.

Solução de problemas

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 na leitura do segredo Política de acesso do Key Vault ou de RBAC ausente Conceda a função Key Vault Secrets User à identidade do agente. Se estiver usando políticas de acesso do Key Vault, conceda a permissão Get para segredos.
O repositório aparece como com falha no 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.