> 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/ja-gitbook-documentation/docs-as-code/git-sync/troubleshooting.md).
# トラブルシューティング
これらの解決策を使って、一般的な Git Sync とリポジトリの問題を解決してください。トピックを展開すると、関連する確認事項と次の手順が表示されます。
### 同期エラーとアクセス
保護されたブランチへのプッシュ時のエラー
このエラーは、Git ブランチが保護されているときに発生します:
```
エラー: refs/heads/main の保護されたブランチにプッシュするための権限がありません。Git プロバイダーでブランチ設定を確認してください。
```
Git Sync では、セットアップ中も含め、制限なく変更をリポジトリにプッシュするために GitBook アプリが必要です。同期を機能させるには、GitBook アプリがブランチ保護を回避できるようにしてください。
GitBook は、アプリがそれらを回避できるように許可されている限り、次のブランチ保護をサポートします:
* マージ前にプルリクエストを必須にする
* 一致するブランチへのプッシュを許可するユーザーを制限する
GitHub で、リポジトリのブランチ保護設定を開き、 `gitbook-com` がこれらの制限を回避できるように許可してください。
Git Sync のステータスに予期しないエラーが表示される
**GitBook で変更リクエストをマージしたときにエラーが表示された場合:** 小さな変更（たとえば単語を 1 つ追加するなど）を加えた新しい変更リクエストを作成し、マージしてください。これにより同期が再実行され、GitBook は失敗した同期の変更も含め、すべてのコンテンツを再エクスポートします。
**GitHub または GitLab のコミットをマージしたときにエラーが表示された場合:** 小さな変更を加えた新しいコミットをリポジトリに作成してください。マージされると、GitBook は失敗した同期の変更も含め、リポジトリ内のすべてのコンテンツを再インポートします。
**初回セットアップ中にエラーが表示された場合:** GitHub または GitLab の連携を削除し、セクションで再度有効にして、セットアップ手順をもう一度実行してください。
これらの手順で解決しない場合は、 [サポートに連絡してください](/docs/documentation/ja-gitbook-documentation/herupu/contact-support.md).
Git 認証に失敗しました
このメッセージは、GitBook へのアクセスを許可していないリポジトリにプッシュしようとしたときに表示されます。その場合、リポジトリから GitBook への同期は機能しますが、その逆は機能せず、リポジトリが正しく一覧表示されないことがあります。
GitHub の場合は、GitHub の設定でアクセスを許可してください。 **組織を管理 → 統合 → アプリケーション**、クリックします **設定** の GitBook の横で、GitBook アプリがアクセスできるリポジトリを選択します。
GitLab の場合は、アクセストークンに次の権限が設定されていることを確認してください: `api`, `read_repository`、および `write_repository` アクセス。
GitHub プレビューが表示されない
GitHub プレビューが表示されない場合は、GitSync の連携が 2022 年 1 月より前に設定されている可能性があります。この日付より前に設定された GitSync のバージョンには GitHub Preview が含まれていません。
PR への読み取り専用アクセスを有効にするため、更新された権限要求を承認するよう求める通知を受け取っているはずです。
通知を受け取っていない場合は、トラブルシューティングのために新しいバージョンに更新する必要があります:
1. 組織から GitSync 連携をアンインストールします。
2. 更新された権限を持つ新しいバージョンを再インストールします。
GitSync 連携をアンインストールすると、以前接続されていた各セクションで連携を再設定する必要があることに注意してください。
### リポジトリの内容と構造
Git Sync のファイルサイズ制限
Git Sync では、個々のファイルサイズの上限は 100 MB です。パフォーマンスと同期速度を向上させるため、リポジトリ内のファイルとアセットのサイズを最適化してください。
目次が正しく構成されていません
あなたの `SUMMARY.md` ファイルは GitBook 上の目次を反映します — その構造はコンテンツに反映されます。ドキュメントで見せたい構造がファイルに反映されていることを確認してください。 [コンテンツ設定](/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync/content-configuration.md#summary) を参照してください。
Git Sync はプルリクエストも同期しますか？
いいえ。GitHub または GitLab でプルリクエストを作成しても GitBook で変更リクエストは作成されず、GitBook で変更リクエストを作成してもリポジトリにプルリクエストは作成されません。
### 一般的な Git Sync の問題
GitHub 同期エラーがあります
#### リポジトリに README ファイルを作成する
Git Sync が有効なときは、GitBook の UI から readme ファイルを作成しないよう注意してください。GitBook の UI から readme ファイルを作成すると、
* リポジトリに重複した README ファイルが作成されます
* GitBook と GitHub の間でレンダリングの競合が発生します
* ビルドやデプロイのプロセスが壊れる可能性があります
* ファイルの優先順位が予測不能になります
これには README.md、readme.md、Readme.md、README（拡張子なし）の各ファイルが含まれます。代わりに、README ファイルは git リポジトリで直接管理するようにしてください。
#### まだエラーが発生しますか？
次の点を確認してください:
* あなたのリポジトリ **に** `README.md` **ファイル** がルートに存在するか、または `root` に指定されたフォルダ `.gitbook.yaml`に存在し、そのファイルが git リポジトリで直接作成されていること。このファイルは必須であり、ドキュメントのホームページとして使用されます。詳しくは、 [コンテンツ設定](/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync/content-configuration.md).
* Markdown ファイルに YAML frontmatter がある場合は、 [リンター](http://www.yamllint.com)で妥当性が確認されていることを確認してください。
GitBook が私の docs フォルダ
を使用していません [コンテンツ設定](/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync/content-configuration.md) についてのドキュメントをご覧ください。詳細は
GitBook が新しい Markdown ファイルを作成しています
**GitBook から同期および編集しているときに** 既存の Git リポジトリに対して、GitBook が既存のファイルの代わりに新しい Markdown ファイルを作成することがあります。これは、GitBook がリポジトリ内に以前から存在していたファイルを上書きしないようにするためです。
リダイレクトが正しく機能しません
リダイレクトを機能させるには、YAML ファイルが正しくフォーマットされている必要があります。インデントや空白の誤りなどのエラーにより、リダイレクトが機能しないことがあります。 [YAML ファイルを検証する](https://www.yamllint.com/) ことで、リダイレクトがスムーズに機能することを確認できます。
リダイレクトを設定するときは、先頭にスラッシュを付けないでください。たとえば、次へリダイレクトしようとしても `./misc/support.md` は機能しません。
また、あるパスにページが存在する限り、GitBook は可能なリダイレクトを探しません。そのため、古いページから新しいページへのリダイレクトを設定する場合は、リダイレクトを機能させるために古いページを削除する必要があります。
リポジトリが一覧に表示されません
#### GitHub リポジトリ
GitBook GitHub アプリを正しい場所にインストールしていること（アプリをインストールするときに、個人の GitHub にインストールするか、権限のある組織にインストールするかを選択できます）、そしてアプリに正しいリポジトリ権限を付与していることを確認してください。
#### GitLab リポジトリ
アクセストークンに次のアクセス権が設定されていることを確認してください:
* `api`
* `read_repository`
* `write_repository`
リポジトリにファイルを追加しても何も起こりません
{% hint style="warning" %}
**このセクションでは、特に `SUMMARY.md` ファイルが既に存在する**
場合の問題を扱います `SUMMARY.md` リポジトリに
{% endhint %}
ファイルが含まれていない場合、GitBook は最初の同期時に自動的に作成します。つまり、Git sync を設定した後に少なくとも 1 回 GitBook からコンテンツを編集していれば、GitBook がこのファイルを自動的に作成しているはずです。 [あなたの `SUMMARY.md` ファイル](/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync/content-configuration.md#summary)。
これは、ファイルを手動で作成した場合、または GitBook で編集を行い、同期の GitBook から Git へのエクスポート段階で GitBook が作成した場合のいずれかです。
このファイルの内容は、GitBook 上のあなたの [目次](/docs/documentation/ja-gitbook-documentation/rifarensu/gitbook-ui.md#table-of-contents) を反映しており、同期の Git から GitBook へのインポート段階で、目次を再作成し、リポジトリからの今後の更新を GitBook 上の既存コンテンツと再調整するために使用されます。
すべてのファイルが `SUMMARY.md` ファイルに含まれていることを確認しても、GitBook でまだ何も起こらない場合は、 [サポートに連絡してください](/docs/documentation/ja-gitbook-documentation/herupu/contact-support.md) 遠慮なくご連絡ください。
サインイン時にアカウントが重複します
このエラーは通常、同期の設定に使用した GitHub アカウントが、別の GitBook ユーザーアカウントに既に関連付けられている場合に発生します。
GitHub アカウントがすでにどの GitBook アカウントにリンクされているかを特定する良い方法は次のとおりです:
1. 現在の GitBook ユーザーセッションからログアウトします（つまり、 `name@email.com`)
2. GitHub のユーザーセッションからすべてログアウトします。
3. へ移動します [ログインページ](https://app.gitbook.com/login).
4. 「GitHub でサインイン」オプションを選択します。
5. GitHub の認証情報を入力します。
6. ログインしたら、 [アカウント設定](https://app.gitbook.com/account) に移動し、次のいずれかを行います:
1. 個人設定の「Third-party Login > GitHub」セクションからアカウントのリンクを解除する
2. 不要であれば、アカウント自体を削除する。
7. セッションからログアウトします。
8. 再度 `name@email.com` GitBook アカウント
9. でログインし直します。
安全でないファイルが Git Sync をブロックしています
スペースに、GitBook がエクスポートに安全でないと判断するファイル（たとえば `.js`).
次のようなエラーが表示されることがあります:
> `ファイル「」は安全でないと見なされるためエクスポートできません`
安全でないファイルは、Git リポジトリからだけでなく GitBook のスペースからも削除する必要があります。
1. 影響を受けているスペースで変更リクエストを作成する
2. を開き **ファイル** タブ
3. 安全でないファイルを削除する
4. 変更リクエストをマージする
安全でないファイルがスペースから削除されると、Git Sync は通常どおり再開するはずです。
---
# 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/ja-gitbook-documentation/docs-as-code/git-sync/troubleshooting.md?ask=&goal=
```
`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.