Configurar el conector de aplicación BYO de GitHub en Azure SRE Agent

Conecte el agente a GitHub mediante una aplicación Bring Your Own GitHub, una identidad de servicio que su organización registra con credenciales respaldadas por Key Vault.

Importante

En este tutorial se configura el acceso basado en aplicaciones a los repositorios de GitHub mediante una aplicación byO GitHub con credenciales respaldadas por Key Vault. Todas las operaciones se atribuyen a la identidad de la aplicación, no a un usuario individual.

Cuándo usar la aplicación BYO

Use la aplicación BYO cuando:

  • Su organización requiere controles de autenticación y custodia de claves basados en aplicaciones.
  • Se va a conectar a repositorios *.ghe.com (obligatorios).
  • Quiere acceso mediante tokens de instalación en lugar de tokens de usuario.

Prerequisites

  • Ejecutar el agente con el rol de administrador o de usuario estándar
  • Una aplicación GitHub creada en el host de destino (github.com o *.ghe.com)
  • Acceso de administrador de GitHub a la organización o al repositorio (para crear, instalar o verificar el alcance de GitHub App)
  • Clave privada de la aplicación almacenada en Azure Key Vault como secreto
  • Identidad administrada asignada al agente con el rol de Usuario de secretos de Key Vault en ese almacén

Paso 1: Crear una aplicación de GitHub

Si ya tiene una aplicación de GitHub con los permisos adecuados, vaya a Step 2.

  1. Vaya al host de GitHub:
    • github.com: Vaya a la organización, a continuación, seleccione Settings>Configuración del desarrollador>GitHub Apps>Nuevo GitHub App.
    • <tenant>.ghe.com: La misma ruta en tu instancia de GHE.
  2. Rellene los detalles de la aplicación:
    • GitHub Nombre de la aplicación: por ejemplo, contoso-sre-agent-reader (prefijo con el nombre de la organización para evitar conflictos).
    • Dirección URL de la página principal: https://sre.azure.com.
    • Webhook: desactive Active (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. Tenga en cuenta el identificador de cliente que se muestra en la página Configuración de la aplicación (comienza por Iv..., esto es diferente del identificador numérico 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. Elija Todos los repositorios o seleccione repositorios específicos.
  4. Seleccione Instalar.

Paso 2: Generación de una clave privada

  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.

Advertencia

Mantenga el PEM a salvo. Cargue esta clave en Key Vault en el paso siguiente. No lo suba a un repositorio ni lo comparta.

Paso 3: Almacenar la clave privada en Key Vault

  1. Abra el portal Azure y vaya a la Key Vault.
  2. Vaya a SecretsGenerate/Import (>).
  3. Establezca Nombre (por ejemplo, sre-agent-github-app-key) y pegue el contenido PEM completo como valor (incluidos -----BEGIN RSA PRIVATE KEY----- los encabezados y -----END RSA PRIVATE KEY----- ).
  4. Selecciona Crear.
  5. Abra el secreto, seleccione la versión actual y copie el URI del Identificador de secreto:
https://myvault.vault.azure.net/secrets/my-github-app-key/<version>

Tip

Use el URI con versión (con el sufijo /<version>) para fijar una versión específica de la clave, o bien omita la versión para usar siempre la más reciente. Se recomienda sin versión. Al girar la clave, el agente recoge automáticamente la nueva versión sin actualizar el URI.

Paso 4: Concesión de acceso Key Vault a la identidad del agente

  1. En Azure portal, abra el Key Vault y vaya a Control de acceso (IAM).
  2. Asigne Key Vault Secrets User a la identidad administrada del agente.
  3. Espere a que se propague la asignación de roles.

Paso 5: Configurar BYO App en Code Access

  1. Abra su agente.
  2. Vaya a Builder>Acceso al código.

Captura de pantalla de la página de Acceso al código en la navegación de Builder en Azure SRE Agent.

  1. Seleccione Agregar repositorios.

  2. Elija GitHub y escriba el host:

    • github.com para GitHub público.
    • <tenant>.ghe.com para Enterprise Cloud.
  3. Continúe con Autenticación.

  4. Seleccione Bring your own GitHub App.

    Captura de pantalla del formulario de autenticación de la aplicación BYO de GitHub que muestra los campos Id. de cliente y URI de Key Vault.

  5. Escriba:

    • Id de cliente
    • URI del secreto de la clave privada (Key Vault)
    • Identidad de Key Vault opcional (o mantener la asignada por el sistema)
  6. 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.

Captura de pantalla del estado correcto de Conectado como aplicación de GitHub, con una marca de verificación verde.

Nota:

Si aparece la marca de verificación en verde y Conectado como aplicación de GitHub, sus credenciales son válidas. Si Connect produce un error, compruebe el identificador de cliente, Key Vault URI y los permisos de identidad administrada.

Si El acceso a código no se abre desde el panel de navegación izquierdo, actualice la página del agente, vuelva a expandir Builder y vuelva a intentarlo.

Importante

Cuando introduces un dominio *.ghe.com como host, el asistente selecciona automáticamente Usar su propia aplicación de GitHub. OAuth y PAT no están disponibles para los hosts de GHE.

Paso 6: Incorporación de repositorios y comprobación

  1. Seleccione repositorios y guarde.

    Captura de pantalla del paso de selección del repositorio que muestra los repositorios disponibles que se van a agregar.

  2. Confirme que la tarjeta Acceso al código muestra el host conectado y el tipo de autenticación GitHubApp.

    Captura de pantalla de la página de acceso de código que muestra el host de GitHub conectado con el tipo de autenticación de GitHubApp.

  3. Probar el acceso al código en chat:

What files are in the root of owner/repo?

Si también ha concedido el permiso de Problemas a su GitHub App, compruebe las operaciones de problemas:

List recent issues from owner/repo.

Identidad administrada por aplicación

De forma predeterminada, el agente usa su identidad administrada asignada por el sistema para leer la clave privada de Key Vault. Si gestiona varias aplicaciones de GitHub (por ejemplo, una por cada instancia de GHE), asigne una identidad administrada asignada por el usuario distinta a cada aplicación. Este enfoque proporciona aislamiento de seguridad porque cada identidad solo tiene acceso a su propio secreto de Key Vault.

Seleccione la identidad en la lista desplegable Key Vault identity durante el paso 5.

Compatibilidad con varios hosts para conectores de GitHub

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

  • github.com: aplicación OAuth, PAT o 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.
Error en la lectura del secreto Falta directiva de acceso o RBAC de Key Vault Conceda Usuario de secretos de Key Vault a la identidad del agente. Si usa las directivas de acceso de Key Vault, conceda el permiso Get para los secretos.
El repositorio muestra Error en acceso del código Faltan permisos de aplicación o ámbito de instalación Verificar metadatos: Lectura + contenido: ámbito de lectura e 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.