Comment connecter Apidog à GitHub et GitLab

Si vos spécifications d'API sont dans Apidog mais que votre source de vérité est dans Git, configurez l'intégration Git d'Apidog pour garder les deux synchronisés. Vous pouvez connecter GitHub, GitLab ou Azure DevOps, pousser vos fichiers OpenAPI dans le contrôle de version, récupérer les changements du dépôt dans Apidog, et conserver un historique exploitable pour la revue, l'audit et la restauration.

Essayez Apidog dès aujourd’hui

Cette référence explique comment utiliser l'intégration Git d'Apidog de façon concrète : choisir le bon mode, connecter un fournisseur Git, structurer vos branches, gérer les permissions, éviter les conflits et dépanner les erreurs courantes. Si vous cherchez uniquement le pas-à-pas GitHub, consultez le guide dédié pour synchroniser votre spécification OpenAPI avec GitHub.

Ce que fait l'intégration Git d'Apidog

Apidog communique avec Git de deux manières. Avant de configurer quoi que ce soit, choisissez le mode qui correspond à votre workflow.

1. Synchronisation bidirectionnelle avec le mode Spec-First

Utilisez ce mode si votre équipe traite la spécification OpenAPI comme du code.

Flux typique :

1. Vous éditez le fichier OpenAPI en YAML ou JSON dans Apidog.
2. Vous validez vos changements.
3. Vous poussez vers la branche Git connectée.
4. Vous récupérez aussi dans Apidog les modifications faites depuis le dépôt.

Ce mode est adapté aux équipes qui veulent :

• des pull requests sur les changements d'API ;
• une revue de code sur le YAML OpenAPI ;
• un historique Git clair ;
• la possibilité de revenir à une version précédente.

2. Sauvegarde Git automatique

Utilisez ce mode si vous voulez surtout une copie versionnée de vos spécifications.

Flux typique :

1. Vous configurez un dépôt Git pour un module Apidog.
2. Apidog exporte automatiquement le fichier OpenAPI/Swagger du module.
3. Le fichier est poussé vers Git selon un calendrier, pendant une fenêtre nocturne hors pointe.

Ce mode est unidirectionnel : Apidog écrit dans Git, mais ne récupère pas les changements du dépôt.

Capacité	Direction	Déclencheur	Idéal pour
Synchronisation en mode Spec-First	Bidirectionnel : push et pull	Commit/push manuel, pull manuel	Les équipes qui traitent la spécification comme du code
Sauvegarde Git automatique	Unidirectionnel : Apidog → Git	Planifié, heures creuses	Les équipes qui veulent une sauvegarde versionnée sans changer leur workflow

Retenez cette distinction :

• Synchronisation = aller-retour entre Apidog et Git.
• Sauvegarde = export automatique d'Apidog vers Git.

Fournisseurs Git pris en charge

Apidog prend en charge GitHub, GitLab et Azure DevOps.

Fournisseur	Méthode d'authentification	Notes
GitHub	Autorisation OAuth	Fonctionne avec les dépôts personnels et d'organisation. Les dépôts d'organisation peuvent nécessiter l'approbation d'un administrateur.
GitLab	Autorisation OAuth	Prend en charge gitlab.com et les instances auto-gérées accessibles depuis Apidog.
Azure DevOps	Connexion Git générique : HTTPS + jeton	Utilisez l'URL HTTPS du dépôt et un jeton d'accès personnel avec les droits nécessaires sur le dépôt.

La connexion Git générique est utile pour Azure DevOps et pour les hôtes Git accessibles en HTTPS avec authentification par jeton.

Connecter votre fournisseur Git

Le processus général est le même pour chaque fournisseur :

1. Autoriser Apidog à accéder au fournisseur Git.
2. Sélectionner un dépôt.
3. Sélectionner une branche.
4. Lier le projet Apidog à cet emplacement Git.

Connecter GitHub

Pour GitHub :

1. Ouvrez les paramètres Git dans votre projet Apidog.
2. Choisissez GitHub comme fournisseur.
3. Autorisez Apidog via l'écran OAuth GitHub.
4. Sélectionnez le dépôt.
5. Sélectionnez la branche cible, par exemple main.

Si le dépôt appartient à une organisation, GitHub peut exiger l'approbation d'un administrateur. Si l'autorisation semble réussir mais que le dépôt n'apparaît pas dans Apidog, vérifiez d'abord ce point.

Connecter GitLab

Pour GitLab :

1. Choisissez GitLab comme fournisseur.
2. Connectez-vous via l'écran OAuth GitLab.
3. Accordez l'accès au dépôt.
4. Sélectionnez le dépôt et la branche.

Pour une instance GitLab auto-gérée, assurez-vous qu'Apidog peut atteindre l'instance via le réseau.

Connecter Azure DevOps

Pour Azure DevOps, utilisez la connexion Git générique.

Étapes :

1. Dans Azure DevOps, créez un jeton d'accès personnel, ou PAT.
2. Donnez au PAT les permissions de lecture et d'écriture sur le code pour le projet cible.
3. Copiez l'URL HTTPS du dépôt.
4. Dans Apidog, choisissez la connexion Git générique.
5. Collez l'URL HTTPS du dépôt.
6. Collez le PAT.
7. Sélectionnez la branche à utiliser.

Bonnes pratiques pour le PAT :

• limitez-le au projet ou dépôt nécessaire ;
• évitez les jetons à accès complet ;
• stockez-le comme un secret ;
• faites-le pivoter régulièrement ;
• révoquez-le si la personne qui l'a créé quitte l'équipe.

Si vous débutez avec les conventions Git pour OpenAPI, consultez aussi le guide sur le contrôle de version OpenAPI avec Git.

Synchronisation bidirectionnelle avec le mode Spec-First

Le mode Spec-First transforme Apidog en éditeur OpenAPI connecté à Git. Vous pouvez consulter la documentation officielle d'Apidog, mais voici le workflow pratique.

Workflow recommandé

1. Tirez les derniers changements depuis Git.
2. Modifiez la spécification dans Apidog.
3. Vérifiez la validation en direct.
4. Commitez avec un message clair.
5. Poussez vers la branche connectée.
6. Ouvrez une pull request si vous travaillez sur une branche de fonctionnalité.

Exemple de message de commit :

Add GET /v1/orders/{orderId} endpoint

Exemple de modification OpenAPI

Supposons que vous ajoutiez un endpoint pour récupérer une commande :

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'

Dans Apidog, l'éditeur vous aide à repérer les problèmes courants :

• $ref incorrect ;
• champ obligatoire manquant ;
• structure YAML invalide ;
• schéma mal formé.

Après l'enregistrement, Apidog considère la modification comme locale. Vous pouvez ensuite la valider et la pousser vers Git. Lorsque le push est terminé, l'indicateur de synchronisation confirme que la branche et Apidog sont alignés.

Récupérer les changements du dépôt

La synchronisation est aussi importante dans l'autre sens. Si un coéquipier modifie le fichier OpenAPI dans Git, récupérez les changements dans Apidog avant de continuer.

Règle simple :

Pull avant de modifier, push après validation.

Cela réduit fortement les conflits.

Annuler des modifications non poussées

Si vous avez fait des tests que vous ne voulez pas conserver, utilisez l'option d'annulation des modifications non poussées. Apidog revient alors au dernier état synchronisé avec Git.

Ce workflow correspond à un workflow API Git-native : la conception d'API suit les mêmes pratiques que le code applicatif.

Sauvegarde Git automatique des spécifications d'API

La sauvegarde automatique est plus simple : vous configurez le dépôt une fois, puis Apidog pousse régulièrement les fichiers OpenAPI/Swagger exportés.

Quand l'utiliser

Utilisez la sauvegarde automatique si vous voulez :

• conserver une copie versionnée de chaque module ;
• comparer une spécification actuelle avec une ancienne version ;
• restaurer une version précédente depuis Git ;
• garder un historique sans imposer de nouveau workflow à l'équipe.

Fonctionnement

Pour chaque module configuré :

1. Apidog exporte le fichier OpenAPI/Swagger.
2. Apidog pousse le fichier dans le dépôt Git choisi.
3. Chaque push crée un commit.
4. Git conserve l'historique des versions.

Le push est exécuté pendant une fenêtre nocturne aléatoire hors pointe. Cela évite de perturber le travail quotidien et répartit la charge.

Important : ce flux est unidirectionnel. Si quelqu'un modifie le fichier dans Git, la sauvegarde automatique ne réimporte pas cette modification dans Apidog. Pour cela, utilisez le mode Spec-First.

Choisir une branche et une structure de dépôt

La structure Git influence directement la qualité du workflow.

Choix de la branche

Deux approches sont courantes.

Option 1 : synchroniser avec main

Simple et rapide.

À utiliser si :

• l'équipe est petite ;
• les changements de spécification sont peu risqués ;
• vous n'avez pas besoin de revue systématique.

Limite : les changements arrivent directement sur la branche canonique.

Option 2 : utiliser des branches de fonctionnalité

Plus robuste.

Exemple :

git checkout -b api/add-order-endpoint

Workflow :

1. Connectez Apidog à une branche de fonctionnalité.
2. Modifiez la spécification.
3. Poussez les changements.
4. Ouvrez une pull request.
5. Faites relire le diff OpenAPI.
6. Fusionnez dans main.

C'est l'approche recommandée si votre API est utilisée par plusieurs équipes ou clients.

Un dépôt ou plusieurs dépôts

Un dépôt par API

Avantages :

• historique plus lisible ;
• permissions plus précises ;
• ownership clair par équipe.

À privilégier si chaque API appartient à une équipe différente.

Monorepo pour toutes les spécifications

Avantages :

• centralisation ;
• recherche plus simple ;
• revue inter-API plus facile.

Si vous utilisez un monorepo, gardez une structure prévisible :

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

Attribuez un chemin distinct à chaque module pour éviter les collisions entre sauvegardes ou synchronisations.

Permissions et accès de l'équipe

L'intégration Git manipule des identifiants. Configurez les droits avec prudence.

Dans Apidog

Définissez qui peut :

• lire la spécification ;
• modifier la spécification ;
• synchroniser ;
• pousser vers Git.

Bonne pratique : limitez les droits de push aux personnes responsables de la spécification.

Dans le fournisseur Git

Pour GitHub et GitLab, l'accès dépend de l'utilisateur qui autorise Apidog via OAuth.

Pour Azure DevOps et les connexions génériques, l'accès dépend du PAT fourni.

Checklist sécurité :

• utiliser un jeton à portée limitée ;
• éviter les jetons personnels trop larges ;
• ne jamais partager le jeton dans un document ou un canal non sécurisé ;
• révoquer les jetons inutilisés ;
• renouveler le jeton si le propriétaire quitte l'équipe.

Le principe : l'intégration est aussi sécurisée que l'identifiant utilisé pour l'autoriser.

Gérer les conflits de fusion et la dérive

Comme Apidog écrit un historique Git réel, les conflits Git restent possibles.

Exemple de conflit

Scénario :

1. Vous modifiez le schéma Order dans Apidog.
2. Un coéquipier modifie le même schéma dans Git.
3. Il pousse avant vous.
4. Votre synchronisation rencontre un conflit sur le YAML.

Ce n'est pas un problème spécifique à Apidog. C'est un conflit Git classique sur un fichier YAML.

Réduire les conflits

Appliquez ces règles :

• récupérez les changements avant de modifier ;
• évitez de modifier le même schéma à plusieurs en parallèle ;
• utilisez des branches de fonctionnalité ;
• relisez les diffs OpenAPI dans les pull requests ;
• gardez les fichiers YAML valides après résolution.

Exemple de réflexe avant modification :

1. Pull depuis Git
2. Modifier dans Apidog
3. Valider
4. Push

Résoudre un conflit

Lorsqu'un conflit survient :

1. Ouvrez le YAML concerné.
2. Identifiez les sections en conflit.
3. Conservez les lignes correctes.
4. Supprimez les marqueurs de conflit.
5. Vérifiez que le document OpenAPI reste valide.
6. Resynchronisez.

La validation en direct d'Apidog aide à détecter rapidement les erreurs de structure après fusion.

Surveiller la dérive

La dérive apparaît lorsque l'état d'Apidog et celui du dépôt ne sont plus alignés. L'indicateur de synchronisation est votre signal principal.

Si l'état n'affiche pas que tout est synchronisé :

• poussez les changements locaux en attente ;
• ou récupérez les changements distants ;
• ou résolvez le conflit bloquant.

Dépannage

Avant de chercher un problème complexe, vérifiez l'authentification, la branche et l'état de synchronisation.

Symptôme	Cause probable	Solution
L'autorisation échoue ou le dépôt n'apparaît pas	L'organisation n'a pas approuvé l'accès tiers, ou le jeton manque de portée	Demandez à un administrateur d'approuver l'application GitHub/GitLab ; pour Azure DevOps, recréez le PAT avec les droits de lecture/écriture sur le code
Push rejeté	Jeton révoqué, expiré ou sans permission d'écriture	Réautorisez le fournisseur ; pour une connexion générique, générez un nouveau PAT et mettez-le à jour dans Apidog
Modifications poussées mais non visibles	Mauvaise branche sélectionnée	Vérifiez que la branche connectée correspond à la branche attendue
Synchronisation bloquée	Modifications locales non poussées ou récupération nécessaire	Validez et poussez les changements en attente ; si un coéquipier a poussé, récupérez d'abord
Conflit de fusion sur la spécification	Deux modifications sur les mêmes lignes YAML	Résolvez le conflit comme un conflit Git classique, gardez le document valide, puis resynchronisez
Sauvegarde non exécutée	La fenêtre nocturne planifiée n'est pas encore passée	Attendez le cycle suivant ou vérifiez la configuration du dépôt et de la branche
Modifications expérimentales à abandonner	Changements locaux avant commit	Annulez les modifications non poussées pour revenir au dernier état synchronisé

Dans la majorité des cas, le problème vient d'un jeton révoqué, d'une portée insuffisante ou d'une approbation d'organisation manquante.

FAQ

La synchronisation est-elle unidirectionnelle ou bidirectionnelle ?

Cela dépend de la fonctionnalité.

Le mode Spec-First est bidirectionnel : vous poussez les modifications vers Git et récupérez les changements du dépôt dans Apidog.

La sauvegarde automatique est unidirectionnelle : Apidog exporte la spécification vers Git selon un calendrier, sans récupérer les changements du dépôt.

Où mes spécifications sont-elles stockées ?

Dans le dépôt Git que vous configurez.

Avec le mode Spec-First, le document OpenAPI se trouve sur la branche connectée.

Avec la sauvegarde automatique, le fichier OpenAPI/Swagger exporté de chaque module est validé dans le dépôt configuré.

Dans les deux cas, Git conserve la copie versionnée.

Vers quelle branche dois-je synchroniser ?

Utilisez main pour la spécification canonique.

Pour les modifications en cours, utilisez une branche de fonctionnalité afin de passer par une pull request avant fusion.

Que se passe-t-il si mon jeton est révoqué ?

Les pushes échouent, car Apidog n'a plus l'accès en écriture.

Solution :

1. Réautorisez GitHub ou GitLab.
2. Ou, pour Azure DevOps et les connexions génériques, créez un nouveau PAT.
3. Mettez à jour l'identifiant dans Apidog.
4. Relancez la synchronisation ou attendez le prochain cycle de sauvegarde.

Conclusion

L'intégration Git d'Apidog fournit deux workflows complémentaires :

• mode Spec-First pour synchroniser OpenAPI dans les deux sens et traiter la spécification comme du code ;
• sauvegarde automatique pour pousser régulièrement les spécifications vers Git sans changer le travail quotidien.

Si vous voulez une revue systématique des changements d'API, utilisez le mode Spec-First avec des branches de fonctionnalité et des pull requests. Si vous voulez surtout un historique versionné et restaurable, activez la sauvegarde automatique. Beaucoup d'équipes utilisent les deux : Git devient alors à la fois le lieu de collaboration et le filet de sécurité pour leurs contrats d'API.