Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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.como*.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.
- 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.
-
- 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).
-
GitHub Nombre de la aplicación: por ejemplo,
- 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.
- En ¿Dónde se puede instalar esta aplicación GitHub?, seleccione Only en esta cuenta.
- Seleccione Crear aplicación de GitHub.
- 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
- En la página GitHub Configuración de la aplicación, seleccione Instalar aplicación en la barra lateral izquierda.
- Seleccione su organización.
- Elija Todos los repositorios o seleccione repositorios específicos.
- Seleccione Instalar.
Paso 2: Generación de una clave privada
- En la página GitHub Configuración de la aplicación, desplácese hasta Claves privadas.
- Seleccione Generar una clave privada.
- Se descarga un
.pemarchivo. 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
- Abra el portal Azure y vaya a la Key Vault.
- Vaya a SecretsGenerate/Import (>).
- 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-----). - Selecciona Crear.
- 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
- En Azure portal, abra el Key Vault y vaya a Control de acceso (IAM).
- Asigne Key Vault Secrets User a la identidad administrada del agente.
- Espere a que se propague la asignación de roles.
Paso 5: Configurar BYO App en Code Access
- Abra su agente.
- Vaya a Builder>Acceso al código.
Seleccione Agregar repositorios.
Elija GitHub y escriba el host:
-
github.compara GitHub público. -
<tenant>.ghe.compara Enterprise Cloud.
-
Continúe con Autenticación.
Seleccione Bring your own GitHub App.
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)
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.
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
Seleccione repositorios y guarde.
Confirme que la tarjeta Acceso al código muestra el host conectado y el tipo de autenticación
GitHubApp.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. |