GitHub Pages サイトの Jekyll ビルド エラーについて

Jekyll がローカルまたはGitHub PagesでGitHub サイトのビルド中にエラーが発生した場合は、詳細情報を含むエラー メッセージが表示されます。

この機能を使用できるユーザーについて

GitHub Pagesは、パブリック・リポジトリのGitHub Freeと組織用のGitHub Free、パブリック・リポジトリとプライベート・リポジトリのGitHub Pro、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Serverで利用できます。 詳細については、「GitHubのプラン」を参照してください。

この記事で

メモ

github-pages gem は一部のワークフローで引き続きサポートされますが、GitHub Actions サイトのデプロイと自動化のための推奨される方法は GitHub Pages になりました。

Jekyllのビルドエラーについて

ブランチから発行する場合、変更をサイトの発行元にプッシュした後、 GitHub Pages がサイトのビルドを試みない場合があります。

  • 変更をプッシュしたユーザーがメールアドレスを検証していない。 詳細については、 AUTOTITLE を参照してください。
  • デプロイキーでプッシュしている。 サイトのリポジトリへのプッシュを自動化する場合は、かわりにマシンユーザーを設定できます。 詳しくは、「デプロイキーの管理」をご覧ください。
  • あなたのCIサービスは公開用ソースをビルドするように設定されていません。 たとえば、Travis CI は、ブランチをセーフ リストに追加しない限り、gh-pages ブランチをビルドしません。 詳細については、Travis CI の「ビルドのカスタマイズ」またはお使いの CI サービスのドキュメントを参照してください。

メモ

変更を GitHubにプッシュした後、サイトへの変更が発行されるまでに最大 10 分かかる場合があります。

Jekyll がサイトのビルドを試み、エラーが発生すると、ビルド エラー メッセージが表示されます。

ビルド エラーのトラブルシューティングの詳細については、「GitHub Pages サイトの Jekyll ビルド エラーのトラブルシューティング」を参照してください。

GitHub Actions を使用した Jekyll のビルド エラー メッセージの表示

既定では、GitHub Pages サイトは、別の CI ツールを使用するように GitHub Actions サイトを構成していない限り、GitHub Pages ワークフロー実行で構築および展開されます。 潜在的なビルドエラーを見つけるには、リポジトリのワークフロー実行履歴を確認して、GitHub Pages サイトのワークフロー実行を確認できます。 詳しくは、「ワークフロー実行の履歴を表示する」をご覧ください。 エラーが発生した場合にワークフローを再実行する方法の詳細については、「ワークフローとジョブの再実行」を参照してください。

ローカルでのJekyllビルドエラーメッセージの表示

サイトをローカルでテストすることをお勧めします。これにより、コマンド ラインにビルド エラー メッセージが表示され、 GitHubに変更をプッシュする前にビルドエラーに対処できます。 詳しくは、「Jekyll を使用して GitHub Pages サイトをローカルでテストする」をご覧ください。

Pull Request中でのJekyllのビルドエラーメッセージの表示

ブランチから発行する場合、 GitHubで発行元を更新するプル要求を作成すると、pull request の [ チェック ] タブにビルド エラー メッセージが表示されます。 詳しくは、「ステータスチェックについて」をご覧ください。

カスタム GitHub Actions ワークフローを使用して発行する場合、pull request でビルド エラー メッセージを表示するには、 pull_request トリガーで実行するようにワークフローを構成する必要があります。 これを行う際は、ワークフローが pull_request イベントによってトリガーされた場合に、展開手順をスキップすることをお勧めします。 これにより、pull request からの変更をサイトにデプロイすることなく、ビルド エラーを確認することができます。 詳細については、「ワークフローをトリガーするイベント」および「ワークフロー内とアクション内で式を評価する」を参照してください。

メールでのJekyllのビルドエラーメッセージの表示

ブランチから発行する場合、 GitHubで発行元に変更をプッシュすると、 GitHub Pages はサイトの構築を試みます。 ビルドが失敗すると、プライマリメールアドレスにメールが送信されます。

カスタム GitHub Actions ワークフローを使用して発行する場合、pull request でビルド エラーに関する電子メールを受信するには、 pull_request トリガーで実行するようにワークフローを構成する必要があります。 これを行う際は、ワークフローが pull_request イベントによってトリガーされた場合に、展開手順をスキップすることをお勧めします。 これにより、pull request からの変更をサイトにデプロイすることなく、ビルド エラーを確認することができます。 詳細については、「ワークフローをトリガーするイベント」および「ワークフロー内とアクション内で式を評価する」を参照してください。

サードパーティCIサービスでのPull Request中でのJekyllのビルドエラーメッセージの表示

各コミット後にエラー メッセージを表示するように、Travis CI などのサードパーティのサービスを構成できます。

  1. 公開ソースのルートに、以下の内容で Gemfile と呼ばれるファイルをまだ追加していない場合は、追加します。

    source `https://rubygems.org`
gem `github-pages`

  2. 選択したテストサービス用にサイトのリポジトリを設定します。 たとえば、Travis CI を使用するには、公開ソースのルートに .travis.yml という名前のファイルを追加し、次の内容を含めます。

    language: ruby
rvm:
  - 2.3
script: "bundle exec jekyll build"

  3. サードパーティのテストサービス内で、リポジトリを有効にする必要があるかもしれません。 詳しい情報については、お使いのテストサービスのドキュメンテーションを参照してください。