> 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 Sync とリポジトリの問題を解決してください。トピックを展開すると、関連する確認事項と次の手順が表示されます。

### 同期エラーとアクセス

<details>

<summary>保護されたブランチを持つリポジトリにプッシュする際のエラー</summary>

このエラーは、Git ブランチが保護されている場合に発生します:

```
エラー: refs/heads/main の保護されたブランチにプッシュする権限がありません。Git プロバイダーでブランチ設定を確認してください。
```

Git Sync では、セットアップ中を含め、GitBook アプリが制限なしにリポジトリへ変更をプッシュする必要があります。同期を機能させるには、GitBook アプリがブランチ保護をバイパスできるようにしてください。

GitBook は、アプリにそれらをバイパスする許可がある限り、次のブランチ保護をサポートしています:

* マージ前にプルリクエストを必須にする
* 一致するブランチへのプッシュを許可するユーザーを制限する

GitHub でリポジトリのブランチ保護設定を開き、 `gitbook-com` がこれらの制限を回避できるようにします。

</details>

<details>

<summary>Git Sync のステータスに予期しないエラーが表示される</summary>

**GitBook で変更リクエストをマージしたときにエラーが発生した場合:** 単語を追加するなど、小さな変更を加えた新しい変更リクエストを作成してマージします。これにより同期が再度実行され、失敗した同期での変更を含むすべてのコンテンツが GitBook にエクスポートされます。

**GitHub または GitLab からコミットをマージしたときにエラーが発生した場合:** リポジトリに小さな変更を加えた新しいコミットを作成します。マージされると、失敗した同期での変更を含むすべてのコンテンツが GitBook に再度インポートされます。

**初回セットアップ中にエラーが発生した場合:** GitHub または GitLab のインテグレーションを削除し、セクションで再度有効にして、セットアップ手順をもう一度行います。

これらの手順で解決しない場合は、 [サポートにお問い合わせください](https://gitbook.com/docs/documentation/ja-gitbook-documentation/herupu/contact-support.md).

</details>

<details>

<summary>Git 認証に失敗しました</summary>

このメッセージは、GitBook へのアクセスを許可していないリポジトリにプッシュしようとしたときに表示されます。その場合、リポジトリから GitBook への同期は機能しますが、その逆は機能せず、リポジトリが正しく一覧表示されないことがあります。

GitHub の場合は、GitHub の設定でアクセスを許可します。 **Manage Organization → Integrations → Applications**を開き、GitBook の横にある **Configure** をクリックして、GitBook アプリがアクセスできるリポジトリを選択します。

GitLab の場合は、アクセストークンに次の権限が設定されていることを確認してください: `api`, `read_repository`および `write_repository` アクセス権限。

</details>

<details>

<summary>GitHub プレビューが表示されない</summary>

GitHub プレビューが表示されない場合、Git Sync の連携が 2022 年 1 月より前に設定されている可能性があります。この日付より前に設定された Git Sync のバージョンには GitHub Preview が含まれていません。

PR への読み取り専用アクセスを有効にするため、更新された権限要求を承認するよう求める通知を受け取っているはずです。

通知を受け取っていない場合は、トラブルシューティングのために新しいバージョンに更新する必要があります:

1. Git Sync 連携を組織からアンインストールします。
2. 更新された権限で新しいバージョンを再インストールします。

Git Sync 連携をアンインストールすると、以前に接続されていた各セクションで連携を再設定する必要があることに注意してください。

</details>

### リポジトリの内容と構造

<details>

<summary>Git Sync のファイルサイズ制限</summary>

Git Sync では個々のファイルサイズを最大 100MB に制限しています。パフォーマンスと同期速度を向上させるため、リポジトリ内のファイルとアセットのサイズを最適化してください。

</details>

<details>

<summary>目次の構造が正しくありません</summary>

お使いの `SUMMARY.md` ファイルは GitBook の目次を反映します。ファイルの構成はコンテンツに反映されるため、ドキュメントに表示したい構成になっていることを確認してください。想定される形式については、 [コンテンツの設定](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync/content-configuration.md#summary) をご覧ください。

</details>

<details>

<summary>編集後に別のスペースへのリンクが 404 を返す <code>gitbook-docs.yaml</code></summary>

スペース間リンクはスペース ID を使って解決されます。Git Sync は、各スペースを `gitbook-docs.yaml` 内で、その `key`によって識別します。そのため、スペースのキーを変更すると、そのスペースが置き換えられます。GitBook は新しいスペースを作成し、マッピングされたディレクトリからコンテンツをインポートします。元のスペースはサイトから切り離された状態で組織内に残ります。

ページは元に戻りますが、スペース ID は変わります。古い ID を参照するリンク、カード、 `SUMMARY.md` の項目は機能しなくなります。

新しい ID は恒久的なものです。元のキーに戻しても古い ID は復元されず、別の新しい ID を持つスペースがもう一つ作成されます。影響を受ける参照先を現在のスペースに変更し、変更された公開 URL に [サイトリダイレクト](https://gitbook.com/docs/documentation/ja-gitbook-documentation/publish/site-redirects.md) を追加してください。

リポジトリにない情報が必要な場合、元のスペースは引き続き組織内にあります。 [見つからない場合は、](https://gitbook.com/docs/documentation/ja-gitbook-documentation/herupu/contact-support.md) 元のスペース ID を添えてサポートにお問い合わせください。

</details>

<details>

<summary>Git Syncを再接続した後、コンテンツが置き換えられた</summary>

Git Syncを再接続するか、接続を作成し直すと、GitBookは選択した方向に新しい初回同期を実行します。GitHub → GitBookまたはGitLab → GitBookの場合、GitBookは同期対象の各セクションを、選択したブランチのコンテンツで置き換えます。たとえば、最近の変更リクエストがまだエクスポートされていないなどの理由でブランチがGitBookより古い状態だった場合、それらの変更はセクションと公開済みサイトの両方から消えます。

置き換えられたコンテンツは、各セクションのバージョン履歴に残っています。復元するには:

1. セクションの **バージョン履歴**.
2. コンテンツを置き換えたGit Syncのエントリを見つけ、その直前のバージョンを選択します。
3. [ロールバック](https://gitbook.com/docs/documentation/ja-gitbook-documentation/kontentsuwosuru/version-control.md#roll-back-to-a-previous-version) して、そのバージョンに戻します。
4. 同期によって置き換えられた各セクションで、同じ操作を繰り返します。

ロールバック後、復元されたコンテンツがブランチ上の新しいコミットに反映されていることを確認します。リポジトリがまだ古い状態の場合、後からリポジトリとの同期を行うと、コンテンツが再び置き換えられることがあります。

</details>

<details>

<summary>Git Sync はプルリクエストも同期しますか？</summary>

いいえ。GitHub または GitLab でプルリクエストを作成しても GitBook で変更リクエストは作成されず、GitBook で変更リクエストを作成してもリポジトリにプルリクエストは作成されません。

</details>

### 一般的な Git Sync の問題

<details>

<summary>GitHub の同期エラーがあります</summary>

#### リポジトリに 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リポジトリに直接作成されたものです。このファイルは必須で、ドキュメントのホームページとして使用されます。詳しくは、 [コンテンツ設定](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync/content-configuration.md).
* MarkdownファイルにYAMLフロントマターがある場合は、 [リンター](http://www.yamllint.com)を使って有効な形式であることを確認してください。

</details>

<details>

<summary>GitBook が <code>docs</code> フォルダを使用していない</summary>

デフォルトでは、GitBookはリポジトリのルートを開始点として使用します。対象となるMarkdownファイルを絞り込むには、特定のディレクトリを指定できます。詳しくは、 [コンテンツ設定](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync/content-configuration.md) に関するドキュメントをご覧ください。

</details>

<details>

<summary>GitBook が新しい Markdown ファイルを作成している</summary>

**既存のGitリポジトリを使ってGitBookから同期や編集を行う場合、** 既存のMarkdownファイルを使用せず、新しいファイルを作成することがあります。これは、リポジトリにあらかじめ存在していたファイルをGitBookが上書きしないようにするためです。

</details>

<details>

<summary>リダイレクトが正しく機能しない</summary>

リダイレクトを機能させるには、YAML ファイルが正しい形式で記述されている必要があります。インデントや空白が正しくないと、リダイレクトが機能しない場合があります。 [YAML ファイルを検証することで、](https://www.yamllint.com/) リダイレクトが問題なく機能することを確認できます。

リダイレクトを設定する際は、先頭にスラッシュを付けないでください。たとえば、 `./misc/support.md` へのリダイレクトは機能しません。

また、パスにページが存在する限り、GitBook は可能なリダイレクトを探しません。そのため、古いページから新しいページへのリダイレクトを設定する場合は、リダイレクトを機能させるために古いページを削除する必要があります。

</details>

<details>

<summary>リポジトリが一覧に表示されない</summary>

#### GitHub リポジトリ

GitBook GitHub アプリを正しい場所にインストールしていることを確認してください（アプリのインストール時に、自分の個人 GitHub にインストールするか、権限のある任意の組織にインストールするかを選べます）。また、アプリに正しいリポジトリ権限を付与していることも確認してください。

#### GitLab リポジトリ

アクセストークンに次のアクセス権が設定されていることを確認してください:

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

</details>

<details>

<summary>リポジトリにファイルを追加しても何も起こらない</summary>

{% hint style="warning" %}
**このセクションでは、 `SUMMARY.md` ファイルがすでに存在する場合の問題について説明します**

リポジトリに `SUMMARY.md` ファイルがない場合、GitBookは初回の同期時に自動で作成します。つまり、Git Syncの設定後に一度でもGitBookでコンテンツを編集していれば、このファイルは自動的に作成されているはずです。
{% endhint %}

Markdownファイルを追加または変更してリポジトリを更新した後、GitBookに変更が反映されず、同期中にサイドバーにもエラーが表示されない場合は、変更したファイルが [お使いの `SUMMARY.md` ファイルに記載されていない可能性があります](https://gitbook.com/docs/documentation/ja-gitbook-documentation/docs-as-code/git-sync/content-configuration.md#summary)。

これは、ファイルを手動で作成したか、GitBook で編集した際に GitBook から Git へのエクスポート段階で作成されたためかもしれません。

このファイルの内容は、GitBook上の [目次](https://gitbook.com/docs/documentation/ja-gitbook-documentation/rifarensu/gitbook-ui.md#table-of-contents) を反映しています。同期のGitからGitBookへのインポート時に使用され、目次を再作成するとともに、リポジトリからの今後の更新をGitBook上の既存コンテンツと整合させます。

SUMMARY.md `ファイルにすべてのファイルが含まれていることを確認しても` GitBook で何も起きない場合は、お気軽に [サポートにお問い合わせ](https://gitbook.com/docs/documentation/ja-gitbook-documentation/herupu/contact-support.md) ください。

</details>

<details>

<summary>サインイン時に重複したアカウントがある</summary>

このエラーは通常、同期の設定に使用した 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 の設定を試してください。

</details>

<details>

<summary>安全でないファイルが Git Sync を妨げています</summary>

スペースに、GitBookが安全でないと判断してエクスポートできないファイル（例： `.js`).

次のようなエラーが表示される場合があります:

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

安全でないファイルは、Git リポジトリからではなく GitBook スペースから削除する必要があります。

1. 影響を受けるスペースで変更リクエストを作成する
2. 「 **ファイル** 」タブを開きます
3. 安全でないファイルを削除する
4. 変更リクエストをマージする

安全でないファイルがスペースから削除されると、Git Sync は通常どおり再開されるはずです。

</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/ja-gitbook-documentation/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.
