¿Cómo conectar Apidog a GitHub y GitLab?

Si sus especificaciones de API viven en Apidog pero la fuente de verdad está en Git, conecte ambos sistemas para evitar divergencias. La integración Git de Apidog permite vincular un repositorio de GitHub, GitLab o Azure DevOps, enviar especificaciones OpenAPI al control de versiones y traer cambios del repositorio de vuelta a Apidog. El resultado: historial auditable, revisión de cambios mediante Git y una copia versionada de sus contratos de API.

Prueba Apidog hoy

Esta guía resume cómo configurar y operar la integración en la práctica: proveedores soportados, modos de sincronización, permisos, estructura de ramas, conflictos y solución de problemas. Si solo necesita el flujo específico de GitHub, consulte la guía para sincronizar su especificación OpenAPI con GitHub. Aquí cubrimos el flujo completo.

Qué hace la integración Git de Apidog

Apidog se comunica con Git de dos formas. Cada una resuelve un caso distinto:

1. Sincronización bidireccional en Modo Spec-First

   • Edita OpenAPI en Apidog como YAML o JSON.
   • Hace commit y push hacia la rama conectada.
   • Hace pull para traer cambios hechos desde el repositorio.

2. Copia de seguridad automática en Git

   • Apidog exporta las especificaciones OpenAPI/Swagger por módulo.
   • Envía esos archivos a Git de forma programada.
   • Es un flujo unidireccional: Apidog → Git.

Capacidad	Dirección	Disparador	Mejor para
Sincronización en Modo Spec-First	Bidireccional: push y pull	Commit/push manual, pull manual	Equipos que tratan la especificación como código
Copia de seguridad automática de Git	Unidireccional: Apidog → Git	Programado, fuera de horas pico	Equipos que necesitan historial y respaldo sin cambiar su flujo diario

Regla práctica:

• Use sincronización si quiere colaborar sobre la especificación como si fuera código.
• Use copia de seguridad si solo necesita una copia versionada en Git.
• Use ambas si quiere revisión activa y respaldo automático.

Proveedores Git soportados

Apidog soporta GitHub, GitLab y Azure DevOps. GitHub y GitLab usan autorización OAuth. Azure DevOps se conecta mediante una conexión Git genérica con HTTPS y token.

Proveedor	Método de autenticación	Notas
GitHub	OAuth con cuenta de GitHub	Funciona con repositorios personales y de organización. Las organizaciones pueden requerir aprobación de administrador.
GitLab	OAuth con cuenta de GitLab	Soporta gitlab.com e instancias autoalojadas accesibles desde Apidog.
Azure DevOps	Conexión Git genérica: HTTPS + token	Use la URL HTTPS del repositorio y un token de acceso personal con permisos de repositorio.

La conexión Git genérica también sirve para hosts Git compatibles con HTTPS y autenticación por token.

Conectar un proveedor Git

El flujo general es el mismo para todos los proveedores:

1. Autorice el acceso a Git.
2. Seleccione el repositorio.
3. Seleccione la rama.
4. Configure el proyecto o módulo de Apidog.
5. Pruebe un push o una copia de seguridad.

GitHub

Para GitHub:

1. Abra la configuración de integración Git en Apidog.
2. Elija GitHub.
3. Autorice mediante OAuth.
4. Seleccione el repositorio.
5. Seleccione la rama, por ejemplo main.

Si el repositorio pertenece a una organización, es posible que un administrador de GitHub deba aprobar la integración. Si Apidog no puede listar el repositorio después de autorizar, revise primero esa aprobación.

GitLab

Para GitLab:

1. Elija GitLab como proveedor.
2. Inicie sesión mediante OAuth.
3. Conceda acceso al repositorio.
4. Seleccione repositorio y rama.

Para GitLab autogestionado, asegúrese de que la instancia sea accesible desde Apidog.

Azure DevOps

Para Azure DevOps use la conexión Git genérica:

1. Copie la URL HTTPS del repositorio.
2. Cree un Personal Access Token en Azure DevOps.
3. Dé al token permisos de lectura/escritura sobre código.
4. Pegue la URL y el token en Apidog.
5. Seleccione la rama de trabajo.

Ejemplo de URL HTTPS:

https://dev.azure.com/org/project/_git/api-specs

Buenas prácticas para el token:

• Limítelo al proyecto o repositorio necesario.
• No use tokens de cuenta completa.
• Rótelo periódicamente.
• Revóquelo cuando una persona deje el equipo.

Para preparar su repositorio antes de sincronizar, también puede revisar la guía sobre control de versiones de OpenAPI con Git.

Sincronización bidireccional con el Modo Spec-First

El Modo Spec-First convierte Apidog en un editor OpenAPI conectado a Git. Puede consultar la documentación oficial de Apidog, pero el flujo práctico es:

1. Abra la especificación en Apidog.
2. Edite YAML o JSON.
3. Valide la especificación en el editor.
4. Haga commit.
5. Haga push hacia la rama conectada.
6. Haga pull cuando existan cambios remotos.

Ejemplo de endpoint OpenAPI:

paths:
  /v1/orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve a single order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'

Flujo recomendado antes de cada cambio:

pull → editar → validar → commit → push

Esto reduce conflictos y mantiene Apidog alineado con el repositorio.

El editor de Apidog ayuda con:

• Resaltado de sintaxis.
• Validación en vivo.
• Autocompletado.
• Navegación por rutas, operaciones y esquemas.
• Detección temprana de errores como $ref inválidos o campos requeridos faltantes.

Cuando el push se completa, el indicador de sincronización muestra que Apidog y la rama conectada están alineados.

Este patrón encaja con un flujo de trabajo de API nativo de Git: las especificaciones pasan por commits, pull requests, revisiones, aprobaciones y reversión como cualquier otro archivo del proyecto.

Copia de seguridad automática de Git

La copia de seguridad automática es útil cuando no quiere cambiar el flujo de edición diario, pero sí quiere que Git mantenga una copia versionada de las especificaciones.

El flujo es:

1. Seleccione el módulo de Apidog.
2. Configure el repositorio de destino.
3. Configure la rama o ruta.
4. Guarde la configuración.
5. Apidog envía la especificación OpenAPI/Swagger automáticamente.

Apidog hace push durante una ventana nocturna aleatoria fuera de horas pico. Cada push crea un commit, por lo que puede:

• Comparar la especificación de hoy con una versión anterior.
• Ver cuándo cambió un campo.
• Recuperar una versión previa desde Git.
• Mantener una copia externa al estado de la aplicación.

Importante: este flujo es unidireccional. Si edita el archivo en Git, esos cambios no vuelven automáticamente a Apidog mediante la copia de seguridad. Para eso use el Modo Spec-First.

Elegir rama y estructura de repositorio

Antes de conectar Apidog, decida cómo organizar las especificaciones.

Opción 1: sincronizar con main

Útil para:

• Equipos pequeños.
• Cambios de bajo riesgo.
• Flujos simples sin revisión formal.

Desventaja: se omite la revisión mediante pull request.

Opción 2: sincronizar con ramas de trabajo

Útil para:

• Equipos que revisan cambios de API.
• Cambios contractuales importantes.
• Flujos con pull requests.

Ejemplo:

main
feature/add-orders-endpoint
feature/update-auth-schema

Flujo recomendado:

crear rama → conectar/editar → push → pull request → revisión → merge

Un repositorio por API

Ventajas:

• Historial limpio por API.
• Permisos más específicos.
• Menor riesgo de colisión entre equipos.

Use esta opción si diferentes equipos poseen diferentes APIs.

Monorepo de especificaciones

Ventajas:

• Todas las APIs en un solo lugar.
• Revisión centralizada.
• Búsqueda más simple entre contratos.

Estructura recomendada:

api-specs/
  orders/
    openapi.yaml
  payments/
    openapi.yaml
  users/
    openapi.yaml

Si usa monorepo, asigne una ruta propia a cada módulo para evitar colisiones entre copias de seguridad o sincronizaciones.

Permisos y acceso del equipo

La integración depende de permisos en dos niveles:

1. Permisos en Apidog
2. Permisos en el proveedor Git

En Apidog, limite quién puede sincronizar y hacer push. Una configuración típica:

Rol	Permiso sugerido
Owners de API	Editar, sincronizar, hacer push
Revisores	Leer y comentar/revisar
Consumidores internos	Solo lectura

En GitHub y GitLab, OAuth usa los permisos del usuario que autorizó la integración. En Azure DevOps o conexiones genéricas, el PAT es la credencial efectiva.

Buenas prácticas:

• Use tokens con alcance mínimo.
• Evite tokens personales compartidos por todo el equipo.
• Rote credenciales.
• Revoque tokens inactivos.
• Use una cuenta activa y controlada para integraciones críticas.

Manejar conflictos de fusión y desincronización

Los conflictos ocurren cuando dos personas modifican la misma parte de la especificación antes de sincronizar.

Ejemplo típico:

1. Usted edita el esquema Order en Apidog.
2. Un compañero edita el mismo esquema en Git.
3. El compañero hace push primero.
4. Usted intenta sincronizar.
5. Git detecta conflicto en el YAML.

Esto se resuelve como cualquier conflicto Git.

Ejemplo simplificado:

components:
  schemas:
    Order:
<<<<<<< HEAD
      required:
        - id
        - status
=======
      required:
        - id
        - total
>>>>>>> origin/main

Resolución posible:

components:
  schemas:
    Order:
      required:
        - id
        - status
        - total

Después de resolver:

1. Verifique que el YAML sea válido.
2. Confirme que la estructura OpenAPI sea correcta.
3. Haga commit.
4. Vuelva a sincronizar.

Para reducir conflictos:

• Haga pull antes de editar.
• No edite grandes bloques compartidos sin coordinar.
• Separe cambios por ramas.
• Revise el diff antes del push.
• Mantenga esquemas grandes organizados.

Si el indicador no muestra que todo está sincronizado, trate el estado como pendiente: puede haber cambios sin push o cambios remotos sin pull.

Solución de problemas

Síntoma	Causa probable	Solución
La autorización falla o el repositorio no aparece	Falta aprobación de organización o el token no tiene alcance suficiente	Pida aprobación al administrador de GitHub/GitLab; en Azure DevOps, regenere el PAT con lectura/escritura de código
Push rechazado	Token revocado, caducado o sin permiso de escritura	Vuelva a autorizar el proveedor o actualice el PAT
Cambios enviados pero no visibles	Rama incorrecta	Verifique la rama conectada en Apidog y en Git
La sincronización queda atascada	Hay ediciones locales sin push o cambios remotos pendientes	Haga commit/push o haga pull antes de sincronizar
Conflicto de fusión	Dos cambios sobre las mismas líneas	Resuelva el conflicto en YAML y valide OpenAPI
La copia de seguridad no se ejecutó	Aún no llegó la ventana nocturna programada	Espere el siguiente ciclo o revise repositorio, rama y permisos
Guardó cambios experimentales que no quería conservar	Ediciones locales antes del commit	Use la opción de descartar ediciones no enviadas

Si el problema es intermitente, empiece por revisar credenciales. La mayoría de fallos se deben a:

• Tokens revocados.
• Tokens caducados.
• Falta de permisos de escritura.
• Aprobación de organización pendiente.
• Rama mal seleccionada.

Preguntas frecuentes

¿La sincronización es unidireccional o bidireccional?

Depende del modo:

• Modo Spec-First: bidireccional. Apidog hace push a Git y también puede traer cambios desde Git.
• Copia de seguridad automática: unidireccional. Apidog exporta la especificación hacia Git según un cronograma.

¿Dónde se almacenan mis especificaciones?

En el repositorio Git conectado.

En Modo Spec-First, el documento OpenAPI reside en la rama configurada. En la copia de seguridad automática, Apidog confirma el archivo OpenAPI/Swagger exportado del módulo en el repositorio elegido.

¿A qué rama debo sincronizar?

Use main para la especificación canónica. Para cambios en curso, use ramas de trabajo y pull requests.

Ejemplo:

main
feature/add-orders-api
feature/change-payment-schema

¿Qué pasa si se revoca mi token?

Los pushes fallarán porque Apidog ya no tendrá permiso de escritura. Vuelva a autorizar GitHub/GitLab o genere un nuevo PAT para Azure DevOps y conexiones genéricas.

Después de restaurar la credencial, la sincronización y las copias de seguridad pueden continuar normalmente.

Conclusión

La integración Git de Apidog ofrece dos flujos complementarios:

• Modo Spec-First para trabajar la especificación OpenAPI como código, con commits, push, pull y revisión.
• Copia de seguridad automática para guardar versiones de las especificaciones en Git sin cambiar el flujo diario.

Si necesita control de cambios y revisión, configure el Modo Spec-First. Si necesita respaldo versionado, active la copia de seguridad. En muchos equipos, la mejor opción es usar ambos: Git como fuente de verdad y Apidog como entorno de edición, validación y sincronización de especificaciones API.