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

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

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

GitHub Pagesは、パブリック・リポジトリのGitHub Freeと組織用のGitHub Free、パブリック・リポジトリとプライベート・リポジトリのGitHub Pro、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Serverで利用できます。

この記事で

メモ

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

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

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

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

メモ

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

Jekyll がサイトのビルドを試み、エラーが発生すると、ビルド エラー メッセージが表示されます。 Jekyll ビルドエラーメッセージには主に 2 つのタイプがあります。

  • 「Page build warning」メッセージは、ビルドは成功したものの、今後問題が生じないようにするために変更を行なう必要がある可能性が存在することを意味します。
  • 「Page build failed」メッセージは、ビルドが完了できなかったことを意味します。 Jekyll が失敗の理由を検出できた場合、説明を含むエラーメッセージが表示されます。

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

GitHub であなたのリポジトリのビルドの失敗を表示する

サイトのリポジトリの [Settings] タブで、サイトのビルドの失敗 (ビルドの警告は除く) を確認できます。

ローカルでの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 Enterprise Server インスタンス 上で送信メールのサポートが有効になっている場合にのみ、メールを受信します。 詳しい情報については、サイト管理者にお問い合わせください。

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