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

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

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

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

GitHub Pages で、Jekyll ビルドの実行に GitHub Actions が使用されるようになりました。 ビルドのソースとしてブランチを使用する際、組み込みの Jekyll ワークフローを使用する場合は、リポジトリで GitHub Actions を有効にする必要があります。 GitHub Actions が使用できない場合、または無効になっている場合は、ソース ブランチのルートに .nojekyll ファイルを追加すると、Jekyll ビルド プロセスがバイパスされ、コンテンツが直接デプロイされます。 GitHub Actions の有効化の詳細については、「リポジトリの GitHub Actions の設定を管理する」を参照してください。

この記事の内容

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

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

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

注: サイトに対する変更は、その変更を GitHub にプッシュしてから公開されるまでに、最大 10 分かかることがあります。

Jekyll がサイトのビルドを試行せず、エラーが発生した場合は、ビルド エラー メッセージが表示されます。

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

GitHub ActionsでJekyllのビルドエラーメッセージを表示する

デフォルトでは、GitHub PagesサイトはGitHub Pagesサイトが別のCIツールを使うように設定しないかぎり、GitHub Actionsワークフローの実行でビルドされ、デプロイされます。 ビルドの潜在的なエラーを見つけるには、リポジトリのワークフロー実行をレビューすることによって、GitHub Pagesサイトのためのワークフローの実行をチェックできます。 詳しくは、「ワークフロー実行の履歴を表示する」を参照してください。 エラーが発生した場合のワークフローの再実行について詳しくは、「ワークフローとジョブの再実行」をご覧ください。

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

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

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

ブランチから公開している場合、GitHub の公開ソースを更新するために pull request を作成すると、その pull request の [チェック] タブにビルド エラー メッセージが表示されます。 詳しくは、「ステータスチェックについて」を参照してください。

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

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

ブランチから公開している場合は、GitHub 上の公開元に変更をプッシュしたときに、GitHub Pages によって、サイトのビルドが試行されます。 ビルドが失敗すると、プライマリメールアドレスにメールが送信されます。

カスタムの GitHub Actions ワークフローを使用して公開している場合、pull request でのビルド エラーに関する Email を受信するには、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. サードパーティのテストサービス内で、リポジトリを有効にする必要があるかもしれません。 詳しい情報については、お使いのテストサービスのドキュメンテーションを参照してください。