Dépannage
Résolvez les problèmes courants de Git Sync, de dépôt, de redirections et de connexion
Utilisez ces solutions pour résoudre les problèmes courants de Git Sync et de dépôt. Développez un sujet pour trouver les vérifications pertinentes et les prochaines étapes.
Erreurs de synchronisation et accès
Erreur lors de l’envoi vers un dépôt avec une branche protégée
Cette erreur se produit lorsque votre branche Git est protégée :
Erreur : permissions manquantes pour envoyer vers la branche protégée refs/heads/main. Vérifiez la configuration de votre branche chez votre fournisseur Git.Git Sync nécessite que l’application GitBook puisse envoyer les modifications à votre dépôt sans restrictions, y compris pendant la configuration. Autorisez l’application GitBook à contourner les protections de branche pour que la synchronisation fonctionne.
GitBook prend en charge ces protections de branche, tant que l’application est autorisée à les contourner :
Exiger une pull request avant la fusion
Restreindre qui peut envoyer vers les branches correspondantes
Dans GitHub, ouvrez les paramètres de protection de branche de votre dépôt et autorisez gitbook-com à contourner ces restrictions.
L’état de Git Sync affiche une erreur inattendue
Si l’erreur est apparue lors de la fusion d’une demande de modification dans GitBook : créez une nouvelle demande de modification avec un petit changement — par exemple en ajoutant un mot — puis fusionnez-la. Cela relance la synchronisation et GitBook réexporte tout le contenu, y compris les modifications issues de l’échec de la synchronisation.
Si l’erreur est apparue lors de la fusion d’un commit depuis GitHub ou GitLab : créez un nouveau commit dans votre dépôt avec un petit changement. Lorsqu’il est fusionné, GitBook réimporte tout le contenu du dépôt, y compris les modifications issues de l’échec de la synchronisation.
Si l’erreur est apparue lors de la configuration initiale : supprimez l’intégration GitHub ou GitLab, réactivez-la dans votre espace, puis recommencez la procédure de configuration.
Si aucune de ces étapes n’aide, contactez l’assistance.
L’authentification Git a échoué
Ce message apparaît lorsque vous essayez d’envoyer vers un dépôt qui n’a pas accordé l’accès à GitBook. Dans ce cas, la synchronisation du dépôt vers GitBook fonctionne, mais pas dans l’autre sens — et vos dépôts peuvent ne pas être listés correctement.
Pour GitHub, accordez l’accès dans vos paramètres GitHub : ouvrez Gérer l’organisation → Intégrations → Applications, cliquez sur Configurer à côté de GitBook, puis sélectionnez les dépôts auxquels l’application GitBook peut accéder.
Pour GitLab, assurez-vous que votre jeton d’accès est configuré avec api, read_repository, et write_repository accès.
L’aperçu GitHub ne s’affiche pas
Si votre aperçu GitHub ne s’affiche pas, c’est peut-être parce que votre intégration GitSync a été configurée avant janvier 2022. Les versions de GitSync configurées avant cette date n’incluent pas GitHub Preview.
Vous devriez avoir reçu une notification vous demandant d’accepter une demande d’autorisation mise à jour pour activer l’accès en lecture seule aux PR.
Si vous n’avez pas reçu la notification, pour dépanner vous devez passer à la nouvelle version :
Désinstallez l’intégration GitSync de votre organisation.
Réinstallez la nouvelle version avec les autorisations mises à jour.
Notez que la désinstallation de l’intégration GitSync nécessitera de reconfigurer à nouveau l’intégration sur chaque espace auquel elle était précédemment connectée.
Contenu et structure du dépôt
Limitations de taille des fichiers de Git Sync
Git Sync limite la taille individuelle des fichiers à 100 Mo maximum. Pour améliorer les performances et la vitesse de synchronisation, optimisez la taille des fichiers et des ressources dans votre dépôt.
La structure de ma table des matières n’est pas correcte
Votre SUMMARY.md fichier reflète votre table des matières sur GitBook — sa structure se répercute dans votre contenu. Assurez-vous que le fichier reflète la structure que vous souhaitez voir dans votre documentation. Voir Configuration du contenu pour le format attendu.
Mes liens vers un autre espace renvoient une erreur 404 après modification gitbook-docs.yaml
Les liens entre espaces se résolvent via les ID d’espace. Git Sync identifie chaque espace dans gitbook-docs.yaml par son clé, donc modifier la clé d’un espace remplace cet espace : GitBook en crée un nouveau, y importe votre contenu depuis le répertoire associé, et laisse l’espace d’origine dans votre organisation, détaché du site.
Vos pages réapparaissent, mais l’ID de l’espace change. Les liens, cartes et SUMMARY.md entrées qui pointent vers l’ancien ID cessent de fonctionner.
Le nouvel ID est permanent. Restaurer la clé d’origine ne fait pas revenir l’ancien — cela crée un autre nouvel espace avec un autre nouvel ID. Redirigez les références concernées vers l’espace actuel, et ajoutez redirections du site pour les URL publiées qui ont changé.
L’espace d’origine est toujours dans votre organisation si vous avez besoin d’y récupérer quelque chose qui n’est pas dans votre dépôt. Contactez l’assistance avec l’ID de l’espace d’origine si vous ne parvenez pas à le retrouver.
Git Sync synchronise-t-il aussi les pull requests ?
Non. Créer une pull request dans GitHub ou GitLab ne crée pas une demande de modification dans GitBook, et créer une demande de modification dans GitBook ne crée pas une pull request dans votre dépôt.
Problèmes courants de Git Sync
J’ai une erreur de synchronisation GitHub
Créez des fichiers README dans votre dépôt
Lorsque Git Sync est activé, veillez à ne pas créer de fichiers readme via l’interface GitBook. Créer des fichiers readme via l’interface GitBook :
Crée des fichiers README en double dans votre dépôt
Provoque des conflits d’affichage entre GitBook et GitHub
Peut perturber les builds et les processus de déploiement
Entraîne une priorité de fichiers imprévisible
Cela inclut les fichiers nommés README.md, readme.md, Readme.md et README (sans extension). À la place, pensez à gérer votre fichier README directement dans votre dépôt git.
Vous rencontrez encore des erreurs ?
Assurez-vous que :
Votre dépôt a un
README.mdfichier à sa racine (ou dans lerootdossier spécifié dans votre.gitbook.yaml) qui a été créé directement dans votre dépôt git. Ce fichier est requis et sert de page d’accueil pour votre documentation. Pour plus de détails, consultez notre configuration du contenu.Si vous avez des frontmatters YAML dans vos fichiers Markdown, assurez-vous qu’ils sont valides à l’aide d’un linter.
GitBook n’utilise pas mon docs dossier
Par défaut, GitBook utilise la racine du dépôt comme point de départ. Un répertoire spécifique peut être indiqué pour circonscrire les fichiers markdown. Consultez notre documentation sur configuration du contenu pour plus de détails.
GitBook crée de nouveaux fichiers Markdown
Lors de la synchronisation et de la modification depuis GitBook avec un dépôt Git existant, GitBook peut créer de nouveaux fichiers markdown au lieu d’utiliser ceux qui existent déjà. Cela est fait pour s’assurer que GitBook n’écrase pas les fichiers qui existaient dans votre dépôt avant.
Les redirections ne fonctionnent pas correctement
Le fichier YAML doit être correctement formaté pour que les redirections fonctionnent. Des erreurs telles qu’une indentation ou des espaces incorrects peuvent empêcher vos redirections de fonctionner. Validation de votre fichier YAML peut garantir que les redirections fonctionneront correctement.
Lors de la configuration des redirections, n’ajoutez pas de slash initial. Par exemple, essayer de rediriger vers ./misc/support.md ne fonctionnera pas.
Il est également important de noter que tant qu’une page existe pour un chemin, GitBook ne cherchera pas de redirection possible. Donc, si vous configurez une redirection d’une ancienne page vers une nouvelle, vous devrez supprimer l’ancienne page pour que la redirection fonctionne.
Mon dépôt n’est pas répertorié
Dépôts GitHub
Assurez-vous d’avoir installé l’application GitBook GitHub aux bons emplacements (lors de l’installation de l’application, vous pouvez choisir de l’installer sur votre GitHub personnel ou sur toute organisation pour laquelle vous avez des permissions) et d’avoir donné à l’application les autorisations correctes sur le dépôt.
Dépôts GitLab
Assurez-vous que votre jeton d’accès a été configuré avec les accès suivants :
apiread_repositorywrite_repository
Il ne se passe rien après que j’ajoute un fichier à mon dépôt
Cette section traite spécifiquement des problèmes lorsqu’un SUMMARY.md fichier existe déjà
Si votre dépôt n’inclut pas de SUMMARY.md fichier, GitBook en créera automatiquement un lors de la première synchronisation. Cela signifie que si vous avez modifié votre contenu depuis GitBook au moins une fois après avoir configuré Git sync, GitBook aurait dû créer ce fichier automatiquement.
Si, après avoir mis à jour votre dépôt en ajoutant ou en modifiant un fichier markdown, vous ne voyez pas la mise à jour reflétée sur GitBook et que la barre latérale n’indique pas d’erreur pendant la synchronisation, il est probable que votre ou vos fichiers modifiés ne soient pas listés dans votre SUMMARY.md fichier.
Cela peut être dû au fait que vous avez créé le fichier manuellement, ou au fait que vous avez effectué une modification dans GitBook et que la phase d’export de GitBook vers Git l’a créé pour vous.
Le contenu de ce fichier reflète votre table des matières sur GitBook et est utilisé pendant la phase d’import de Git vers GitBook de la synchronisation pour recréer votre table des matières et réconcilier les prochaines mises à jour du dépôt avec votre contenu existant sur GitBook.
Si, après vous être assuré que tous vos fichiers sont inclus dans le SUMMARY.md fichier, il ne se passe toujours rien sur GitBook, n’hésitez pas à contactez l’assistance pour obtenir de l’aide.
J’ai des comptes en double lors de la connexion
Cette erreur se produit généralement lorsque le compte GitHub que vous utilisez pour configurer la synchronisation est déjà associé à un autre compte utilisateur GitBook.
Une bonne façon d’identifier à quel compte GitBook le compte GitHub est déjà lié est la suivante :
Déconnectez-vous de votre session utilisateur GitBook actuelle (c.-à-d.
name@email.com)Déconnectez-vous de toutes les sessions utilisateur GitHub.
Allez à la page de connexion.
Sélectionnez l’option « Se connecter avec GitHub ».
Saisissez vos identifiants GitHub.
Une fois connecté, allez à les paramètres du compte et soit :
Dissociez le compte de la section « Connexion tierce > GitHub » dans le paramètre Personnel
Supprimez complètement le compte si vous n’en avez pas besoin.
Déconnectez-vous de la session.
Reconnectez-vous avec votre
name@email.comcompte GitBook.Essayez de configurer Git Sync à nouveau.
Des fichiers non sécurisés bloquent Git Sync
Git Sync peut échouer si votre espace contient des fichiers que GitBook considère comme non sécurisés à l’exportation (p. ex. .js).
Vous pouvez voir une erreur telle que :
Le fichier "<filename>" ne peut pas être exporté car il est considéré comme non sécurisé
Les fichiers non sécurisés doivent être supprimés de l’espace GitBook, et pas seulement du dépôt Git.
Créez une demande de modification dans l’espace concerné
Ouvrez le Fichiers onglet
Supprimez le ou les fichiers non sécurisés
Fusionnez la demande de modification
Une fois les fichiers non sécurisés supprimés de l’espace, Git Sync devrait reprendre normalement.
Mis à jour
Ce contenu vous a-t-il été utile ?