Skip to content

Latest commit

 

History

History
89 lines (63 loc) · 7.18 KB

about-jekyll-build-errors-for-github-pages-sites.md

File metadata and controls

89 lines (63 loc) · 7.18 KB
Raw
title intro redirect_from product versions topics shortTitle
About Jekyll build errors for GitHub Pages sites
If Jekyll encounters an error building your {% data variables.product.prodname_pages %} site locally or on {% data variables.product.product_name %}, you'll receive an error message with more information.
/articles/viewing-jekyll-build-error-messages
/articles/generic-jekyll-build-failures
/articles/about-jekyll-build-errors-for-github-pages-sites
/github/working-with-github-pages/about-jekyll-build-errors-for-github-pages-sites
{% data reusables.gated-features.pages %}
fpt ghes ghec
*
*
*
Pages
Jekyll build errors for Pages

About Jekyll build errors

If you are publishing from a branch, sometimes {% data variables.product.prodname_pages %} will not attempt to build your site after you push changes to your site's publishing source.{% ifversion fpt or ghec %}

  • The person who pushed the changes hasn't verified their email address. For more information, see "AUTOTITLE."{% endif %}
  • You're pushing with a deploy key. If you want to automate pushes to your site's repository, you can set up a machine user instead. For more information, see "AUTOTITLE."
  • You're using a CI service that isn't configured to build your publishing source. For example, Travis CI won't build the gh-pages branch unless you add the branch to a safe list. For more information, see "Customizing the build" on Travis CI, or your CI service's documentation.

Note

It can take up to 10 minutes for changes to your site to publish after you push the changes to {% data variables.product.product_name %}.

{% ifversion build-pages-with-actions %} If Jekyll does attempt to build your site and encounters an error, you will receive a build error message. {% else %} If Jekyll does attempt to build your site and encounters an error, you will receive a build error message. There are two main types of Jekyll build error messages.

  • A "Page build warning" message means your build completed successfully, but you may need to make changes to prevent future problems.
  • A "Page build failed" message means your build failed to complete. If Jekyll is able to detect a reason for the failure, you'll see a descriptive error message. {% endif %}

For more information about troubleshooting build errors, see "AUTOTITLE."

{% ifversion build-pages-with-actions %}

Viewing Jekyll build error messages with {% data variables.product.prodname_actions %}

By default, your {% data variables.product.prodname_pages %} site is built and deployed with a {% data variables.product.prodname_actions %} workflow run unless you've configured your {% data variables.product.prodname_pages %} site to use a different CI tool. To find potential build errors, you can check the workflow run for your {% data variables.product.prodname_pages %} site by reviewing your repository's workflow runs. For more information, see "AUTOTITLE." For more information about how to re-run the workflow in case of an error, see "AUTOTITLE." {% endif %}

{% ifversion build-pages-with-actions %}{% else %}

Viewing your repository's build failures on {% data variables.product.product_name %}

You can see build failures (but not build warnings) for your site on {% data variables.product.product_name %} in the Settings tab of your site's repository. {% endif %}

Viewing Jekyll build error messages locally

We recommend testing your site locally, which allows you to see build error messages on the command line, and addressing any build failures before pushing changes to {% data variables.product.product_name %}. For more information, see "AUTOTITLE."

Viewing Jekyll build error messages in your pull request

If you are publishing from a branch, when you create a pull request to update your publishing source on {% data variables.product.product_name %}, you can see build error messages on the Checks tab of the pull request. For more information, see "AUTOTITLE."

If you are publishing with a custom {% data variables.product.prodname_actions %} workflow, in order to see build error messages in your pull request, you must configure your workflow to run on the pull_request trigger. When you do this, we recommend that you skip any deploy steps if the workflow was triggered by the pull_request event. This will allow you to see any build errors without deploying the changes from your pull request to your site. For more information, see "AUTOTITLE" and "AUTOTITLE."

Viewing Jekyll build errors by email

If you are publishing from a branch, when you push changes to your publishing source on {% data variables.product.product_name %}, {% data variables.product.prodname_pages %} will attempt to build your site. If the build fails, you'll receive an email at your primary email address. {% data reusables.pages.build-failure-email-server %}

If you are publishing with a custom {% data variables.product.prodname_actions %} workflow, in order to receive emails about build errors in your pull request, you must configure your workflow to run on the pull_request trigger. When you do this, we recommend that you skip any deploy steps if the workflow was triggered by the pull_request event. This will allow you to see any build errors without deploying the changes from your pull request to your site. For more information, see "AUTOTITLE" and "AUTOTITLE."

Viewing Jekyll build error messages in your pull request with a third-party CI service

You can configure a third-party service, such as Travis CI, to display error messages after each commit.

  1. If you haven't already, add a file called Gemfile in the root of your publishing source, with the following content:

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

  2. Configure your site's repository for the testing service of your choice. For example, to use Travis CI, add a file named .travis.yml in the root of your publishing source, with the following content:

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

  3. You may need to activate your repository with the third-party testing service. For more information, see your testing service's documentation.