About Jekyll build errors for GitHub Pages sites

If Jekyll encounters an error building your GitHub Pages site locally or on GitHub, you'll receive an error message with more information.

Who can use this feature?

GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub’s plans.

GitHub Pages now uses GitHub Actions to execute the Jekyll build. When using a branch as the source of your build, GitHub Actions must be enabled in your repository if you want to use the built-in Jekyll workflow. Alternatively, if GitHub Actions is unavailable or disabled, adding a .nojekyll file to the root of your source branch will bypass the Jekyll build process and deploy the content directly. For more information on enabling GitHub Actions, see Managing GitHub Actions settings for a repository.

In this article

About Jekyll build errors

If you are publishing from a branch, sometimes GitHub Pages will not attempt to build your site after you push changes to your site's publishing source.

  • The person who pushed the changes hasn't verified their email address. For more information, see Verifying your email address.
  • 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 Managing deploy keys.
  • 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 GitHub.

If Jekyll does attempt to build your site and encounters an error, you will receive a build error message.

For more information about troubleshooting build errors, see Troubleshooting Jekyll build errors for GitHub Pages sites.

Viewing Jekyll build error messages with GitHub Actions

By default, your GitHub Pages site is built and deployed with a GitHub Actions workflow run unless you've configured your GitHub Pages site to use a different CI tool. To find potential build errors, you can check the workflow run for your GitHub Pages site by reviewing your repository's workflow runs. For more information, see Viewing workflow run history. For more information about how to re-run the workflow in case of an error, see