If Jekyll encounters an error building your GitHub Pages site locally or on GitHub, you'll receive an error message with more information.
While the `github-pages` gem remains supported for some workflows, GitHub Actions is now the recommended approach for deploying and automating GitHub Pages sites.
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.
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.
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 Re-running workflows and jobs.
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 GitHub. For more information, see Testing your GitHub Pages site locally with Jekyll.
If you are publishing from a branch, when you create a pull request to update your publishing source on GitHub, you can see build error messages on the Checks tab of the pull request. For more information, see Status checks.
If you are publishing with a custom GitHub 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 Events that trigger workflows and Evaluate expressions in workflows and actions.
If you are publishing from a branch, when you push changes to your publishing source on GitHub, GitHub Pages will attempt to build your site. If the build fails, you'll receive an email at your primary email address.
If you are publishing with a custom GitHub 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 Events that trigger workflows and Evaluate expressions in workflows and actions.
You can configure a third-party service, such as Travis CI, to display error messages after each commit.
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`
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"
You may need to activate your repository with the third-party testing service. For more information, see your testing service's documentation.