Conexión de repositorios de GitHub Enterprise Cloud al agente de SRE de Azure

Importante

Esta función de Azure SRE Agent se encuentra actualmente en vista previa. Consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure para conocer los términos legales que se aplican a las características de Azure que se encuentran en la versión beta, en versión preliminar o que todavía no se han publicado para que estén disponibles con carácter general.

Conecte repositorios hospedados en GitHub Enterprise Cloud (<TENANT>.ghe.com) o github.com al agente de SRE de Azure mediante una aplicación de GitHub BYO (Bring Your Own). El agente genera tokens de instalación de corta duración a partir de la clave privada de su aplicación, que se almacena en Azure Key Vault y nunca se copia.

Note

BYO GitHub App funciona para hosts github.com y *.ghe.com. Para github.com con OAuth o PAT, consulte Configurar el conector de GitHub.

Cuándo usar la autenticación de la aplicación de GitHub BYO

Use la aplicación BYO cuando:

  • Su organización requiere controles de autenticación y custodia de claves basados en aplicaciones.
  • Está conectando repositorios *.ghe.com (obligatorio porque OAuth y PAT no están disponibles para hosts de GHE).
  • Quiere acceso mediante tokens de instalación en lugar de tokens de usuario.

Prerequisites

Requirement Detalles
Agente de SRE de Azure Un agente en estado En ejecución con el rol Administrador o Usuario estándar
aplicación de GitHub Una aplicación GitHub creada en el host de destino (github.com o <TENANT>.ghe.com)
acceso de administrador de GitHub Acceso de administrador de la organización o del repositorio para crear, instalar o verificar el alcance de GitHub App
Azure Key Vault Un almacén en el que puede almacenar la clave privada de GitHub app
Identidad administrada Capacidad para asignar Key Vault Crypto User en la clave importada a la identidad usada por el agente

Creación de una aplicación de GitHub

Si ya tiene una aplicación de GitHub con los permisos adecuados, pase a Almacenar la clave privada en Azure Key Vault.

  1. Vaya al host de GitHub:
    • github.com: Ve a tu organización >Configuración>Configuración del desarrollador>GitHub Apps>Nueva GitHub App
    • <TENANT>.ghe.com: Misma ruta en tu instancia de GHE
  2. Rellene los detalles de la aplicación:
    • GitHub Nombre de la aplicación: por ejemplo, sre-agent-reader
    • Dirección URL de la página principal: https://sre.azure.com
    • Webhook: desactive Activo (el agente no usa webhooks)
  3. En Permisos, establezca:
    • Permisos > de repositorio Contenido: solo lectura (obligatorio)
    • Permisos > de repositorio Metadatos: solo lectura (seleccionado automáticamente)
    • Opcionalmente, agregue acceso de lectura a Incidencias y Solicitudes de incorporación.
  4. En ¿Dónde se puede instalar esta aplicación GitHub?, seleccione Only en esta cuenta.
  5. Seleccione Crear aplicación de GitHub.
  6. Anote el identificador de cliente que se muestra en la página de configuración de la aplicación.

Instalación de la aplicación de GitHub

  1. En la página GitHub Configuración de la aplicación, seleccione Instalar aplicación en la barra lateral izquierda.
  2. Seleccione su organización.
  3. Seleccione Todos los repositorios o seleccione repositorios específicos.
  4. Seleccione Instalar.

Generación de una clave privada de aplicación GitHub

  1. En la página GitHub Configuración de la aplicación, desplácese hasta Claves privadas.
  2. Seleccione Generar una clave privada.
  3. Se descarga un .pem archivo. Este archivo es la clave privada RSA que usa el agente para autenticarse.

Caution

Mantenga el PEM a salvo. Lo carga en Key Vault en el paso siguiente. No lo suba a un repositorio y no lo comparta.

Almacenar la clave privada en Azure Key Vault

Importa la clave privada de la app de GitHub como clave RSA, no como secreto, con la operación de Sign activada. Convierte el PEM descargado de GitHub a PKCS#8 antes de importar, y luego elimina permanentemente los archivos PEM locales tras una importación exitosa. Para los comandos, véase Almacenar clave privada en Key Vault.

Copia el URI del identificador de clave importada:

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

Tip

URI con versión frente a URI sin versión: Puede usar el URI con versión (con el sufijo /<VERSION>) para fijar una versión específica de la clave, o bien omitir la versión para usar siempre la más reciente. Use el URI sin inversión para que, al girar la clave, el agente recogerá automáticamente la nueva versión sin actualizar el URI.

Conceder acceso a Key Vault a la identidad del agente

  1. En el portal de Azure, abra Key Vault>Access control (IAM).
  2. Asignar Key Vault Crypto User a la identidad seleccionada para el acceso a Key Vault. Limita la asignación a la clave importada, o solo a la bóveda si está dedicada a esta aplicación.
  3. Espere a que la asignación de roles surta efecto.

Configurar la aplicación BYO en acceso del código

  1. Abra su agente en el portal.
  2. Ve a Construir + configurar>Contexto>.
  3. Seleccione Agregar repositorio.
  4. En el paso de Conexión, elige GitHub e introduce una URL completa del Repositorio, como https://<TENANT>.ghe.com/owner/repo.
  5. Si existe una credencial coincidente, elige Nueva conexión en Añadir repositorio con para configurar otra credencial.
  6. En Método de conexión, selecciona Usar tu aplicación de GitHub.
  7. Especifique:
    • Id de cliente
    • URI de clave privada (Key Vault): un /keys/ URI, no un /secrets/ URI
    • Identidad de Key Vault opcional (o mantener la asignada por el sistema)
  8. Seleccione Conectar.

El asistente valida las credenciales. Si la conexión se realiza correctamente, verá Conectado como aplicación de GitHub con una marca de verificación verde.

Note

Cuando la URL del repositorio utiliza un *.ghe.com host, el asistente selecciona Usar tu aplicación de GitHub. OAuth y PAT no están disponibles para los hosts de GHE.

Adición de repositorios y comprobación de la conexión

  1. Selecciona Siguiente para abrir Añadir repositorios, revisa las entradas de los repositorios y los nombres de visualización, y selecciona Guardar.
  2. Confirma que el repositorio aparece en la lista de Acceso al código con su conexión en la columna Conexión.
  3. Prueba en chat:
Get me recent issues from owner/repo.

Identidad administrada por aplicación para varias aplicaciones de GitHub

Por defecto, el agente utiliza su identidad gestionada asignada por el sistema para las operaciones de firma de Key Vault. Si administra varias aplicaciones de GitHub (por ejemplo, una por cada instancia de GHE), puede asignar una identidad administrada asignada por el usuario diferente a cada una. Cada identidad necesita acceso solo a su propia clave de Key Vault.

Seleccione la identidad en la lista desplegable Key Vault identity durante el paso de configuración.

Compatibilidad con varios hosts para conexiones de GitHub

Puede conectar varios hosts de GitHub al mismo agente. Cada host tiene autenticación independiente:

  • github.com → OAuth, PAT o aplicación BYO
  • contoso.ghe.com → aplicación BYO
  • engineering.ghe.com → aplicación BYO (con una aplicación de GitHub diferente)

La desconexión de un host no afecta a otros usuarios.

Solución de problemas

Síntoma Causa probable Corregir
Falla la validación de autenticación Identificador de cliente incorrecto o host incorrecto Compruebe que la aplicación se creó en el mismo host especificado en Acceso al código.
La firma de Key Vault falla URI de clave incorrecto o permisos de clave faltantes Utiliza un URI RSA /keys/ con Sign activado y concede Key Vault Crypto User a la identidad seleccionada.
El repositorio muestra Error en acceso del código Faltan permisos de aplicación o ámbito de instalación Verificar Metadatos: Leer + Contenido: Leer y el alcance de la instalación.
Las incidencias del chat funcionan, pero el acceso del código falla Las comprobaciones de punto de conexión o ruta de acceso difieren Vuelva a ejecutar la prueba de conexión y compruebe el permiso de metadatos.

Paso siguiente