> 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/documentation-as-code/git-sync/troubleshooting.md).

# Dépannage

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 étapes suivantes.

### 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 envoyer 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, tant que l’application est autorisée à les contourner :

* Exiger une pull request avant la fusion
* Restreindre les personnes autorisées à pousser 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.

</details>

<details>

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

**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 relancera la synchronisation et GitBook réexportera tout le contenu, y compris les modifications issues de la synchronisation échouée.

**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 sera fusionné, GitBook importera de nouveau tout le contenu du dépôt, y compris les modifications issues de la synchronisation échouée.

**Si l’erreur est apparue 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 fonctionne, [contactez l’assistance](/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 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.

</details>

<details>

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

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 l’aperçu GitHub.

Vous auriez dû recevoir 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 résoudre le problème vous devez passer à la nouvelle version :

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

Notez que la désinstallation de l’intégration GitSync exigera de reconfigurer à nouveau l’intégration dans 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 de Git Sync</summary>

Git Sync limite la taille des fichiers individuels à 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.

</details>

<details>

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

Votre `SUMMARY.md` fichier reflète votre table des matières sur GitBook — la manière dont il est structuré se reflète dans votre contenu. Assurez-vous que le fichier reflète la structure que vous souhaitez voir dans votre documentation. Voir [Configuration du contenu](/docs/documentation/fr/documentation-as-code/git-sync/content-configuration.md#summary) pour le format attendu.

</details>

<details>

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

Non. La création d’une pull request dans GitHub ou GitLab ne crée pas de demande de modification dans GitBook, et la création d’une demande de modification dans GitBook ne crée pas de 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. La création de 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 processus de build et 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). À la place, pensez à 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** `README.md` **fichier** à sa racine (ou dans le `racine` dossier spécifié dans votre `.gitbook.yaml`) qui a été créé directement dans votre dépôt git. Ce fichier est requis et est utilisé comme page d’accueil de votre documentation. Pour plus de détails, consultez notre [configuration du contenu](/docs/documentation/fr/documentation-as-code/git-sync/content-configuration.md).
* Si vos front matter YAML dans vos fichiers Markdown sont présents, assurez-vous qu’ils sont valides à l’aide d’un [linter](http://www.yamllint.com).

</details>

<details>

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

Par défaut, GitBook utilise la racine du dépôt comme point de départ. Un répertoire spécifique peut être défini pour limiter la portée des fichiers Markdown. Consultez notre documentation sur [configuration du contenu](/docs/documentation/fr/documentation-as-code/git-sync/content-configuration.md) pour plus de détails.

</details>

<details>

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

**Lors de la synchronisation et de l’édition depuis GitBook** avec un dépôt Git existant, GitBook peut créer de nouveaux fichiers Markdown au lieu d’utiliser les fichiers existants. Cela permet de s’assurer que GitBook n’écrase pas les fichiers qui existaient déjà dans votre dépôt.

</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 blancs peuvent empêcher le bon fonctionnement de vos redirections. [Valider votre fichier YAML](https://www.yamllint.com/) 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.

</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 emplacements corrects (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 accordé à l’application les bonnes autorisations de dépôt.

#### 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 que j’ai ajouté un fichier à mon dépôt</summary>

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

Si votre dépôt ne contient 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.
{% 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 reflétée dans 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](/docs/documentation/fr/documentation-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 du processus de synchronisation l’a créé pour vous.

Le contenu de ce fichier reflète votre [table des matières](/docs/documentation/fr/reference/gitbook-ui.md#table-of-contents) 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 mises à jour à venir 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 dans GitBook, n’hésitez pas à [contactez l’assistance](/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 utilisateur GitBook actuelle (c.-à-d. `name@email.com`)
2. Déconnectez-vous de toutes les sessions utilisateur GitHub.
3. Rendez-vous sur [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é, allez dans [les paramètres du compte](https://app.gitbook.com/account) et soit :
   1. Dissociez le compte depuis la section « Connexion via un tiers > GitHub » dans les 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 à l’aide de votre `name@email.com` compte GitBook.
9. Essayez de configurer Git Sync à nouveau.

</details>

<details>

<summary>Des fichiers non sécurisés bloquent Git Sync</summary>

Git Sync peut échouer si votre espace contient des fichiers que GitBook considère comme non sécurisés à exporter (par exemple `.js`).

Vous pouvez voir une erreur du type :

> `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.

1. Créez une demande de modification dans l’espace concerné
2. Ouvrez le **Fichiers** onglet
3. Supprimez le(s) fichier(s) non sécurisé(s)
4. Fusionnez la demande de modification

Une fois les fichiers non sécurisés 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.