Apidog puede conectarse a inquilinos de GitHub Enterprise Cloud con residencia de datos alojados en dominios dedicados *.ghe.com. Después de que un Administrador de la organización configure el inquilino y la aplicación OAuth, los usuarios autorizados del proyecto pueden conectar repositorios y usar flujos de trabajo de importación, copia de seguridad y sincronización de OpenAPI compatibles.
Esta integración es para inquilinos SaaS de GitHub Enterprise Cloud con residencia de datos. No es compatible con GitHub Enterprise Server ni con dominios GitHub personalizados arbitrarios.
Antes de empezar
Necesitas:
- una organización Apidog Enterprise con acceso a la integración
- permiso de Administrador de la organización en Apidog
- un inquilino de GitHub Enterprise Cloud con residencia de datos en un dominio raíz
*.ghe.com, comohttps://company.ghe.com - permiso para crear una aplicación OAuth en ese inquilino
- acceso a las organizaciones, repositorios y ramas de GitHub que planeas conectar
Los usuarios que conectan repositorios también deben tener el permiso de conexión Git a nivel de proyecto relevante en Apidog.
Paso 1: Crear una aplicación OAuth en el inquilino GHE.com
- Inicia sesión en el inquilino GHE.com de tu organización.
- Abre la configuración de Aplicaciones OAuth.
- Crea una nueva aplicación OAuth.
- Introduce un nombre de aplicación identificable.
- Establece la URL de la página de inicio en:
https://apidog.com - Establece la URL de devolución de llamada de autorización en:
https://api.apidog.com/passport/github/callback - Registra la aplicación OAuth.
- Copia el ID de cliente.
- Genera y copia de forma segura el Secreto de cliente.
La URL de devolución de llamada debe coincidir exactamente con la URL documentada de Apidog.
Almacena el Secreto de cliente en tu sistema de gestión de secretos aprobado. No lo coloques en una captura de pantalla, ticket o documento compartido.
Paso 2: Configurar el inquilino GHE.com en Apidog
Solo un Administrador de la organización puede configurar o borrar esta integración.
- Abre la organización de Apidog.
- Ve a Configuración de la organización.
- Abre Integración de GitHub.
- Busca GitHub Enterprise Cloud Data Residency y selecciona Configurar.
- Introduce la URL del host GHE.com, por ejemplo
https://company.ghe.com. - Selecciona Aplicación OAuth como método de autenticación.
- Introduce el ID de cliente de la aplicación OAuth.
- Introduce el Secreto de cliente de la aplicación OAuth.
- Guarda la configuración.
Configura el host del inquilino y las credenciales de la aplicación OAuth a nivel de organización.
Después de guardar, Apidog muestra la URL del host configurado. El Secreto de cliente no se muestra ni se rellena previamente de nuevo.
Al editar la configuración más tarde, dejar el campo Secreto de cliente vacío mantiene el secreto existente. Introduce un nuevo valor solo cuando lo rotes.
Paso 3: Conectar un repositorio desde un proyecto de Apidog
Una vez completada la configuración a nivel de organización:
- abre el proyecto de Apidog requerido;
- inicia un flujo de trabajo de conexión Git o importación Git;
- selecciona GitHub Enterprise Cloud;
- continúa a la página de autorización en el inquilino GHE.com configurado;
- inicia sesión y autoriza la aplicación OAuth;
- selecciona la organización de GitHub;
- selecciona el repositorio y la rama;
- completa la conexión.
La autorización se realiza en el inquilino GHE.com configurado, no en github.com estándar.
Si falta la organización o el repositorio esperado, verifica el acceso de la cuenta de GitHub y la autorización de la aplicación OAuth antes de cambiar la configuración de la organización de Apidog.
Paso 4: Importar un archivo OpenAPI
Para importar un archivo OpenAPI o Swagger desde el repositorio conectado:
- inicia un flujo de trabajo de importación en el proyecto de Apidog;
- elige OpenAPI/Swagger;
- selecciona Repositorio Git;
- elige la organización de GitHub, el repositorio, la rama y el archivo;
- selecciona Continuar;
- elige un Módulo de destino existente o crea uno nuevo;
- completa la importación;
- revisa los endpoints y esquemas importados antes de aceptar el resultado.
Selecciona el repositorio, la rama y el archivo de especificación requeridos por el proyecto.
Usa un proyecto no productivo para la primera importación, especialmente cuando el módulo de destino ya contiene definiciones de API.
Paso 5: Elegir el flujo de trabajo de sincronización continua
La conexión del repositorio puede admitir diferentes flujos de trabajo. Elige una única fuente de verdad y documéntala para el equipo.
| Flujo de trabajo | Usar cuando | Comportamiento importante |
|---|---|---|
| Importación manual | Los cambios se incorporan a Apidog solo cuando se solicitan | Revisa cada importación y módulo de destino |
| Importación programada | El archivo Git permanece como la fuente y Apidog debe actualizarlo a intervalos | Se ejecuta a través del cliente local o un Runner autoalojado según el modo de ejecución configurado |
| Copia de seguridad en Git | El contenido de Apidog debe escribirse en un archivo de repositorio | Configura el repositorio, la rama y la ruta del archivo de destino; las copias de seguridad automáticas se ejecutan durante un período de menor actividad programado aleatoriamente por la noche |
| Modo "Spec-first" | El archivo de especificación es la fuente de verdad y el equipo edita a través de un flujo de trabajo orientado a Git | Este modo está actualmente en beta; la instalación del webhook generalmente requiere permiso de administrador del repositorio |
No configures dos flujos de trabajo automatizados opuestos para el mismo archivo sin una regla clara de resolución de conflictos.
Para la copia de seguridad:
- crea o selecciona la conexión Git en la configuración del proyecto;
- abre Descripción general > Especificación de API del módulo;
- añade o selecciona la especificación OpenAPI;
- habilita Copia de seguridad en el repositorio Git;
- elige la conexión del repositorio, la rama y la ruta del archivo de destino;
- guarda la configuración.
Para una fuente de verdad impulsada por el repositorio, utiliza Importación programada o revisa el Modo "Spec-first".
Paso 6: Verificar la integración
Realiza una pequeña prueba de extremo a extremo:
- confirma que la autorización abre el inquilino GHE.com configurado
- confirma que solo las organizaciones y repositorios esperados están disponibles
- importa un archivo OpenAPI conocido y compara el resultado con la fuente
- prueba la dirección de copia de seguridad o sincronización seleccionada en una rama desechable
- confirma que la protección de ramas y los permisos de repositorio se comportan como se espera
- revisa los registros o errores de sincronización
- rota el Secreto de cliente de la aplicación OAuth y confirma que el proceso de actualización documentado funciona
Si se utiliza la sincronización de webhooks, verifica que el instalador tenga permiso de administrador del repositorio y que el evento push esperado active la sincronización.
Actualizar o borrar la configuración de la organización
Los Administradores de la organización pueden editar la URL del host o el ID de cliente y pueden rotar el Secreto de cliente introduciendo un nuevo valor.
Para eliminar la configuración a nivel de organización, abre Configuración de la organización > Integración de GitHub, busca la integración de residencia de datos y selecciona Borrar configuración.
Una vez borrada la configuración, los usuarios no pueden crear nuevas conexiones de GitHub Enterprise Cloud hasta que la integración se configure de nuevo. Las conexiones existentes pueden requerir reconfiguración o reautorización dependiendo del estado del token y la configuración de la organización.
Solución de problemas
| Problema | Qué verificar |
|---|---|
| La opción de integración no está disponible | Confirma que la organización tiene acceso a la función Enterprise y que eres un Administrador de la organización. |
| OAuth devuelve un error de devolución de llamada | Confirma que la URL de devolución de llamada de la aplicación OAuth es exactamente https://api.apidog.com/passport/github/callback. |
| La autorización abre github.com | Confirma que el host a nivel de organización es el inquilino raíz *.ghe.com previsto. |
| Falta un repositorio | Verifica el acceso del usuario de GitHub autorizado a la organización y al repositorio, y cualquier restricción de OAuth. |
| Un usuario del proyecto no puede crear una conexión | Confirma que el usuario tiene el permiso de conexión Git a nivel de proyecto requerido. |
| La importación o sincronización falla | Verifica la rama seleccionada, la ruta del archivo, el formato del archivo, los permisos del repositorio y los registros de sincronización. |
Límites de seguridad y residencia de datos
- Solo los Administradores de la organización pueden configurar o borrar la integración GHE.com.
- El Secreto de cliente no se muestra después de la configuración.
- Los permisos del proyecto aún controlan quién puede crear o actualizar conexiones Git.
- La autorización OAuth se produce a través del inquilino GHE.com configurado.
- Los permisos OAuth solicitados pueden incluir el acceso necesario para leer organizaciones, repositorios, ramas, importar archivos, escribir copias de seguridad y gestionar webhooks de repositorio cuando lo requiera un flujo de trabajo de sincronización.
La conexión de un inquilino con residencia de datos no demuestra por sí misma que cada categoría de datos relacionados con GitHub o Apidog permanezca en una sola región. GitHub documenta los datos cubiertos por su oferta de residencia y las excepciones relevantes. Apidog es un servicio conectado separado con su propio modelo de almacenamiento e implementación. Revisa la documentación actual de ambos proveedores como parte de una evaluación de residencia de datos o cumplimiento.
Tutoriales de gobernanza de API relacionados:
Estos tutoriales cubren controles complementarios para gobernar un espacio de trabajo de API empresarial:
- Marco de Gobernanza de API — conecta la propiedad, los controles, la evidencia y las decisiones del ciclo de vida.
- Mapeo de grupos SAML con Microsoft Entra ID — asigna acceso de equipo desde grupos de proveedores de identidad.
- Escáner de secretos — revisa posibles credenciales expuestas en activos compatibles de Apidog.
- Registros de auditoría — investiga y exporta la actividad administrativa de la organización.
- Aprovisionamiento SCIM — gestiona usuarios de la organización a lo largo del ciclo de vida de la identidad.
- Políticas empresariales — configura controles de credenciales, membresía, sesiones SSO e invitaciones.
- Equipos de API de autoservicio gobernados — permite equipos creados por miembros manteniendo la supervisión de la propiedad.
- Integración de GitHub Enterprise Cloud — conecta repositorios GHE.com compatibles para flujos de trabajo OpenAPI.
Documentación oficial relacionada: