トラブルシューティング

一般的なGit Sync、リポジトリ、リダイレクト、サインインの問題を解決します

一般的な Git Sync とリポジトリの問題を解決するには、これらの解決策を使ってください。トピックを展開すると、関連する確認事項と次の手順が表示されます。

同期エラーとアクセス

保護されたブランチのあるリポジトリに push するときのエラー

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

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

Git Sync が変更を制限なくリポジトリに push するには、セットアップ時も含めて GitBook アプリが必要です。同期を機能させるには、GitBook アプリにブランチ保護をバイパスすることを許可してください。

GitBook は、アプリがそれらをバイパスできる限り、次のブランチ保護に対応しています:

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

GitHub で、リポジトリのブランチ保護設定を開き、 gitbook-com がこれらの制限をバイパスできるようにしてください。

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

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

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

初回セットアップ中にエラーが表示された場合: GitHub または GitLab の連携を削除し、セクションで再度有効にして、セットアップ手順をもう一度実行してください。

これらの手順で解決しない場合は、 サポートにお問い合わせください.

Git 認証に失敗しました

このメッセージは、GitBook へのアクセスを付与していないリポジトリに push しようとすると表示されます。その場合、リポジトリから GitBook への同期は機能しますが、逆方向は機能しません。また、リポジトリが正しく一覧表示されないことがあります。

GitHub の場合は、GitHub の設定でアクセス権を付与してください。次を開きます: 組織の管理 → 連携 → アプリケーション、をクリックします 設定 GitBook の横で、GitBook アプリがアクセスできるリポジトリを選択します。

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

GitHub プレビューが表示されない

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

PR への読み取り専用アクセスを有効にするため、更新された権限リクエストの承認を求める通知が届いているはずです。

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

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

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

リポジトリの内容と構成

Git Sync のファイルサイズ制限

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

目次の構成が正しくありません

あなたの SUMMARY.md ファイルは GitBook の目次を反映します。構成の仕方がコンテンツに反映されます。ファイルが、ドキュメントに表示したい構造を反映していることを確認してください。詳細は コンテンツの設定 の想定フォーマットを参照してください。

編集したあと、別のスペースへのリンクが 404 を返す gitbook-docs.yaml

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

ページは戻りますが、スペース ID は変更されます。リンク、カード、 SUMMARY.md 旧 ID を参照しているエントリは壊れます。

新しい ID は永続的です。元のキーを復元しても、古い ID は戻りません。別の新しい ID を持つ別の新しいスペースが作成されるだけです。影響を受けた参照先を現在のスペースに付け直し、 サイトリダイレクト 変更された公開 URL については追加してください。

リポジトリにないものが必要な場合、元のスペースは引き続き組織内に残っています。 サポートにお問い合わせください 見つからない場合は、元のスペース ID を添えてください。

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 ファイル がルートに（または ルート あなたの .gitbook.yamlで指定したフォルダーに）直接 git リポジトリで作成されたものが必要です。このファイルは必須で、ドキュメントのホームページとして使用されます。詳しくは、 コンテンツの設定.
• Markdown ファイルに YAML フロントマターがある場合は、 リンターで検証してください。

GitBook が私の docs フォルダー

デフォルトでは、GitBook はリポジトリのルートを開始点として使用します。Markdown ファイルの範囲を絞るために、特定のディレクトリを指定できます。詳細はドキュメントの コンテンツの設定 を参照してください。

GitBook が新しい Markdown ファイルを作成している

GitBook から同期および編集しているときに 既存の Git リポジトリがある場合、GitBook は既存のファイルを使わずに新しい markdown ファイルを作成することがあります。これは、GitBook が以前からリポジトリに存在していたファイルを上書きしないようにするためです。

リダイレクトが正しく機能しない

リダイレクトを機能させるには、YAML ファイルが正しく整形されている必要があります。インデントや空白の誤りなどがあると、リダイレクトが動作しないことがあります。 YAML ファイルを検証する ことで、リダイレクトが問題なく機能するようにできます。

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

また、パスに対応するページが存在する限り、GitBook はリダイレクトの候補を探さないことにも注意してください。そのため、古いページを新しいページへリダイレクトする場合は、リダイレクトを機能させるために古いページを削除する必要があります。

リポジトリが一覧に表示されない

GitHub リポジトリ

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

GitLab リポジトリ

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

• api
• read_repository
• write_repository

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

このセクションでは、次のような場合の問題を扱います: SUMMARY.md すでにファイルが存在する

リポジトリに SUMMARY.md ファイルが含まれていない場合、GitBook は最初の同期時に自動的に作成します。つまり、Git Sync を設定したあとに GitBook で少なくとも 1 回コンテンツを編集していれば、このファイルは GitBook によって自動作成されているはずです。

markdown ファイルを追加または変更してリポジトリを更新しても、その更新が GitBook に反映されず、同期中にサイドバーにもエラーが表示されない場合、変更したファイルはおそらく あなたの SUMMARY.md ファイルに一覧表示されていない可能性があります。

これは、ファイルを手動で作成したか、GitBook で編集した際に、同期の GitBook から Git へのエクスポート段階で GitBook が作成したためのどちらかである可能性があります。

このファイルの内容は、あなたの 目次 を GitBook 上で反映しており、同期の Git から GitBook へのインポート段階で、目次を再作成し、リポジトリからの今後の更新を GitBook 上の既存コンテンツと再調整するために使用されます。

すべてのファイルが SUMMARY.md ファイルに含まれていることを確認してもなお GitBook で何も起こらない場合は、遠慮なく サポートにお問い合わせください サポートにご連絡ください。

サインイン時にアカウントが重複しています

このエラーは通常、同期の設定に使用した GitHub アカウントが、別の GitBook ユーザーアカウントにすでに関連付けられている場合に発生します。

GitHub アカウントがすでにどの GitBook アカウントに紐付いているかを確認するには、次の方法が有効です:

1. 現在の GitBook ユーザーセッションからログアウトします（つまり、 [e-mail])
2. すべての GitHub ユーザーセッションからログアウトします。
3. 次へ移動します: ログインページ.
4. 「GitHub でサインイン」を選択します。
5. GitHub の認証情報を入力します。
6. ログインしたら、次へ移動します: アカウント設定 そして、次のいずれかを行います:

   1. 個人設定の「サードパーティ ログイン > GitHub」セクションでアカウントのリンクを解除する
   2. 不要であれば、アカウントを完全に削除する
7. セッションからログアウトします。
8. 次の方法で再度ログインします: [e-mail] GitBook アカウントを使用します。
9. 再度 Git Sync の設定を試してください。

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

スペースに、GitBook がエクスポートに安全でないと判断するファイルが含まれている場合、Git Sync が失敗することがあります（例: .js).

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

ファイル「<filename>」は安全でないと判断されるためエクスポートできません

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

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

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