> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/fr/docs-as-code/git-sync/troubleshooting.md).

# 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 synchronisation Git 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

<details>

<summary>Erreur lors de l’envoi vers un dépôt avec une branche protégée</summary>

Cette erreur se produit lorsque votre branche Git est protégée :

```
Erreur : autorisations manquantes pour pousser 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 pousser des modifications vers 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, à condition que l’application soit autorisée à les contourner :

* Exiger une pull request avant la fusion
* Restreindre qui peut pousser vers les branches correspondantes

Dans GitHub, ouvrez les paramètres de protection des branches de votre dépôt et autorisez `gitbook-com` à contourner ces restrictions.

</details>

<details>

<summary>L’état de Git Sync affiche une erreur inattendue</summary>

**Si l’erreur s’est produite lors de la fusion d’une demande de modification dans GitBook :** créez une nouvelle demande de modification contenant un changement mineur, comme l’ajout d’un mot, puis fusionnez-la. Cela relance la synchronisation et GitBook exporte à nouveau tout le contenu, y compris les modifications de la synchronisation qui a échoué.

**Si l’erreur s’est produite lors de la fusion d’un commit depuis GitHub ou GitLab :** créez un nouveau commit dans votre dépôt contenant un changement mineur. Lorsqu’il est fusionné, GitBook importe à nouveau tout le contenu du dépôt, y compris les modifications de la synchronisation qui a échoué.

**Si l’erreur s’est produite lors de la configuration initiale :** supprimez l’intégration GitHub ou GitLab, réactivez-la dans votre section, puis recommencez le processus de configuration.

Si aucune de ces étapes ne résout le problème, [contactez le support](https://gitbook.com/docs/documentation/fr/aide/contact-support.md).

</details>

<details>

<summary>Échec de l’authentification Git</summary>

Ce message apparaît lorsque vous essayez de pousser vers un dépôt qui n’a pas accordé l’accès à GitBook. Dans ce cas, la synchronisation de votre dépôt vers GitBook fonctionne, mais pas l’inverse — et vos dépôts peuvent ne pas s’afficher 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 les autorisations `api`, `read_repository`et `write_repository` .

</details>

<details>

<summary>L’aperçu GitHub ne s’affiche pas</summary>

Si l’aperçu GitHub ne s’affiche pas, c’est peut-être parce que votre intégration Git Sync a été configurée avant janvier 2022. Les versions de Git Sync configurées avant cette date n’incluent pas l’aperçu GitHub.

Vous auriez dû recevoir une notification vous demandant d’accepter une demande d’autorisation mise à jour afin d’activer l’accès en lecture seule aux PR.

Si vous n’avez pas reçu la notification, pour résoudre le problème vous devez passer à la nouvelle version :

1. Désinstallez l’intégration Git Sync de votre organisation.
2. Réinstallez la nouvelle version avec les autorisations mises à jour.

Notez que la désinstallation de l’intégration Git Sync nécessitera de reconfigurer l’intégration sur toutes les sections auxquelles elle était précédemment connectée.

</details>

### Contenu et structure du dépôt

<details>

<summary>Limitations de taille des fichiers Git Sync</summary>

Git Sync limite la taille de chaque fichier à un maximum de 100 Mo. Pour améliorer les performances et la vitesse de synchronisation, optimisez la taille des fichiers et des ressources dans votre dépôt.

</details>

<details>

<summary>Ma table des matières n’est pas correctement structurée</summary>

Votre fichier `SUMMARY.md` représente votre table des matières dans GitBook : sa structure se reflète dans votre contenu. Assurez-vous que le fichier correspond à la structure souhaitée pour votre documentation. Consultez [Configuration du contenu](https://gitbook.com/docs/documentation/fr/docs-as-code/git-sync/content-configuration.md#summary) pour connaître le format attendu.

</details>

<details>

<summary>Mes liens vers un autre espace renvoient une erreur 404 après la modification de <code>gitbook-docs.yaml</code></summary>

Les liens entre espaces sont résolus à l’aide des identifiants des espaces. Git Sync identifie chaque espace dans `gitbook-docs.yaml` par sa `key` : modifier la clé d’un espace remplace donc cet espace. GitBook en crée un nouveau, y importe votre contenu depuis le répertoire associé et conserve l’espace d’origine dans votre organisation, détaché du site.

Vos pages sont restaurées, mais l’identifiant de l’espace change. Les liens, les cartes et les entrées de `SUMMARY.md` qui pointent vers l’ancien identifiant ne fonctionnent plus.

Le nouvel identifiant est permanent. Rétablir la clé d’origine ne restaure pas l’ancien espace : cela crée un autre espace avec un nouvel identifiant. Modifiez les références concernées pour qu’elles pointent vers l’espace actuel et ajoutez des [redirections de site](https://gitbook.com/docs/documentation/fr/publish/site-redirects.md) pour les URL publiées qui ont changé.

L’espace d’origine se trouve toujours dans votre organisation si vous avez besoin d’un élément qui ne figure pas dans votre dépôt. [Contactez le support](https://gitbook.com/docs/documentation/fr/aide/contact-support.md) en indiquant l’identifiant de l’espace d’origine si vous ne parvenez pas à le retrouver.

</details>

<details>

<summary>Le contenu a été remplacé après la reconnexion de Git Sync</summary>

Lorsque vous reconnectez Git Sync ou recréez sa connexion, GitBook effectue une nouvelle synchronisation initiale dans le sens que vous choisissez. Avec GitHub → GitBook ou GitLab → GitBook, GitBook remplace chaque section synchronisée par le contenu de la branche sélectionnée. Si la branche était en retard par rapport à GitBook, par exemple parce que des demandes de modification récentes n’avaient pas encore été exportées, ces modifications disparaissent de la section et du site publié.

Le contenu remplacé figure toujours dans l’historique des versions de chaque section. Pour le restaurer :

1. Ouvrez l’ **historique des versions**.
2. Trouvez l’entrée Git Sync qui a remplacé votre contenu, puis sélectionnez la version qui la précède.
3. [Rétablissez](https://gitbook.com/docs/documentation/fr/creer-du-contenu/version-control.md#roll-back-to-a-previous-version) cette version.
4. Répétez l’opération pour chaque section remplacée par la synchronisation.

Après le rétablissement, vérifiez que le contenu restauré apparaît dans un nouveau commit sur votre branche. Si le dépôt est toujours en retard, une synchronisation ultérieure depuis le dépôt peut remplacer à nouveau le contenu.

</details>

<details>

<summary>Git Sync synchronise-t-il aussi les pull requests ?</summary>

Non. Créer une pull request dans GitHub ou GitLab ne crée pas une demande de changement dans GitBook, et créer une demande de changement dans GitBook ne crée pas une pull request dans votre dépôt.

</details>

### Problèmes courants de Git Sync

<details>

<summary>J’ai une erreur de synchronisation GitHub</summary>

#### 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 de rendu entre GitBook et GitHub
* Peut interrompre les builds et les processus de déploiement
* Entraîne une priorité imprévisible des fichiers

Cela inclut les fichiers nommés README.md, readme.md, Readme.md et README (sans extension). Veillez plutôt à gérer votre fichier README directement dans votre dépôt Git.

#### Vous rencontrez toujours des erreurs ?

Assurez-vous que :‌

* Votre dépôt **contient un fichier** `README.md` **à sa racine (ou dans le dossier** indiqué dans votre `root` de votre `.gitbook.yaml`) qui a été créé directement dans votre dépôt Git. Ce fichier est obligatoire et sert de page d’accueil à votre documentation. Pour en savoir plus, consultez notre [configuration du contenu](https://gitbook.com/docs/documentation/fr/docs-as-code/git-sync/content-configuration.md).
* Si vos fichiers Markdown contiennent des métadonnées YAML, veillez à les valider à l’aide d’un [linter](http://www.yamllint.com).​

</details>

<details>

<summary>GitBook n’utilise pas mon dossier <code>docs</code> dossier</summary>

Par défaut, GitBook utilise la racine du dépôt comme point de départ. Vous pouvez spécifier un répertoire précis pour limiter la recherche aux fichiers Markdown qu’il contient. Consultez notre documentation sur la [configuration du contenu](https://gitbook.com/docs/documentation/fr/docs-as-code/git-sync/content-configuration.md) pour en savoir plus.‌

</details>

<details>

<summary>GitBook crée de nouveaux fichiers Markdown</summary>

**Lorsque vous synchronisez et modifiez du contenu 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 permet d’éviter que GitBook écrase des fichiers présents dans votre dépôt avant la synchronisation.

</details>

<details>

<summary>Les redirections ne fonctionnent pas correctement</summary>

Le fichier YAML doit être correctement formaté pour que les redirections fonctionnent. Des erreurs telles qu’une indentation incorrecte ou des espaces superflus peuvent empêcher vos redirections de fonctionner. [La validation de votre fichier YAML](https://www.yamllint.com/) peut garantir le bon fonctionnement des redirections.

Lors de la configuration des redirections, n’ajoutez pas de barre oblique au début. Par exemple, la redirection vers `./misc/support.md` ne fonctionnera pas.

Il est également important de tenir compte du fait que tant qu’une page existe pour un chemin, GitBook ne recherchera pas une éventuelle redirection. Donc, si vous configurez une redirection d’une ancienne page vers une nouvelle, vous devrez supprimer l’ancienne page pour que la redirection fonctionne.

</details>

<details>

<summary>Mon dépôt n’est pas répertorié</summary>

#### 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 dans toute organisation pour laquelle vous avez des autorisations) et d’avoir accordé à l’application les autorisations de dépôt appropriées.

#### Dépôts GitLab

Assurez-vous que votre jeton d’accès a été configuré avec les accès suivants :

* `api`
* `read_repository`
* `write_repository`

</details>

<details>

<summary>Rien ne se passe après l’ajout d’un fichier à mon dépôt</summary>

{% hint style="warning" %}
**Cette section traite spécifiquement des problèmes qui surviennent lorsqu’un fichier `SUMMARY.md` existe déjà**

Si votre dépôt ne contient pas de fichier `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 devrait avoir créé ce fichier automatiquement.‌
{% endhint %}

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 apparaître dans GitBook et que la barre latérale n’indique aucune erreur pendant la synchronisation, il est probable que le ou les fichiers modifiés ne figurent pas dans [votre `SUMMARY.md` fichier](https://gitbook.com/docs/documentation/fr/docs-as-code/git-sync/content-configuration.md#summary).‌

Cela peut être soit parce que vous avez créé le fichier manuellement, soit parce que vous avez effectué une modification dans GitBook et que la phase d’export de GitBook vers Git de la synchronisation l’a créé pour vous.

Le contenu de ce fichier reflète votre [table des matières](https://gitbook.com/docs/documentation/fr/reference/gitbook-ui.md#table-of-contents) dans GitBook. Il est utilisé lors de la phase d’importation de Git vers GitBook de la synchronisation pour recréer votre table des matières et rapprocher les mises à jour à venir du dépôt de votre contenu existant dans GitBook.‌

Si, après avoir vérifié que tous vos fichiers sont inclus dans le `SUMMARY.md` fichier, rien ne se passe toujours sur GitBook, n’hésitez pas à [contactez l’assistance](https://gitbook.com/docs/documentation/fr/aide/contact-support.md) pour obtenir de l’aide.

</details>

<details>

<summary>J’ai des comptes en double lors de la connexion</summary>

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 :

1. Déconnectez-vous de votre session GitBook actuelle (c’est-à-dire `name@email.com`)
2. Déconnectez-vous de toutes les sessions utilisateur GitHub.
3. Accédez à [la page de connexion](https://app.gitbook.com/login).
4. Sélectionnez l’option « Se connecter avec GitHub ».
5. Saisissez vos identifiants GitHub.
6. Une fois connecté, accédez à [les paramètres du compte](https://app.gitbook.com/account) et faites l’une des choses suivantes :
   1. Dissociez le compte de la section « Connexion tierce > GitHub » dans vos paramètres personnels
   2. Supprimez complètement le compte si vous n’en avez pas besoin.
7. Déconnectez-vous de la session.
8. Reconnectez-vous avec votre `name@email.com` Compte GitBook.
9. Essayez de configurer Git Sync à nouveau.

</details>

<details>

<summary>Des fichiers non sûrs bloquent Git Sync</summary>

La synchronisation Git peut échouer si votre espace contient des fichiers que GitBook considère comme dangereux à exporter (par ex. `.js`).

Vous pouvez voir une erreur du type :

> `File "<filename>" cannot be exported as it is considered unsafe`

Les fichiers non sûrs doivent être supprimés de l’espace GitBook, et pas seulement du dépôt Git.

1. Créez une demande de changement dans l’espace concerné
2. Ouvrez l’onglet **Fichiers** .
3. Supprimez le ou les fichiers non sûrs
4. Fusionnez la demande de changement

Une fois les fichiers non sûrs supprimés de l’espace, Git Sync devrait reprendre normalement.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/fr/docs-as-code/git-sync/troubleshooting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
