Generic build failures will not produce an email with specific file and error information. If you receive an email that simply says "Page build failed" with no further details, or your GitHub Pages site is not showing up after the first push, check for these common errors.

We recommend building your site locally to help you troubleshoot generic Jekyll build failures, such as syntax or tag errors.

Deploy key used for push

Pushes must come from a user account. You won't trigger a build if you use a deploy key to push to an organization's Pages repository.

Instead, you can set up a machine user as a member of your organization.

Unsupported plugins

The GitHub Pages server will not build with unsupported plugins. The only way to incorporate unsupported plugins in your site is to generate your site locally and then push your site's static files to your GitHub Pages site. For a list of supported plugins and instructions on how to include them in your GitHub Pages site, see "Adding Jekyll plugins to a GitHub Pages site."

Source setting

Our build server overrides the source setting when it builds Pages sites. If you change this setting in your _config.yml file, your GitHub Pages site may not build correctly.

Working with continuous integration services

Some CI services, such as Travis CI, won't build your gh-pages branch unless you explicitly whitelist it. If you want your GitHub Pages site to integrate with a CI service, you'll need to specify the gh-pages branch in your CI's configuration file.

For example, Travis CI's documentation suggests adding the following lines to a .travis.yml file:

branches:
  only:
    - gh-pages