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.

Unverified email address

To trigger a build, the user who pushes a commit to the Pages repository must have a verified email address.

After you verify an email address, your GitHub Pages sites will build automatically.

Deploy key used for push

Pushes must come from a user account with a verified email address. 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."

Size limits

Repositories on GitHub have a soft limit of 1 GB per repository. Similarly, GitHub Pages sites also have a 1 GB soft limit.

If your Pages site exceeds that limit, you may find that your site won't build. You may also receive a polite email from us requesting that you reduce the size of your 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