GitHub Help

Generic failures

These 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 Enterprise Pages site is not showing up after the first push, check for the following common errors:

Deploy key used for push

If your Pages repository has a deploy key associated with it, pushing to the repository with the deploy key will not trigger a build. Pushes must come from a user account. An alternative to deploy keys is to set up a machine user.

Unsupported plugins

The GitHub Enterprise Pages server will not build with unsupported plugins. For a list of supported plugins and instructions on how to include them in your GitHub Enterprise Pages site, see Using Jekyll Plugins with GitHub Enterprise Pages.

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 Enterprise 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 Enterprise 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

Specific failures

These build failures will produce an email with specific file and error information:

• Markdown errors
• Config file error
• File does not exist in includes directory
• File is a symlink
• File is not properly UTF-8 encoded
• Invalid post date
• Invalid submodule
• Missing submodule
• Tag not properly closed
• Tag not properly terminated
• Unknown tag error

Viewing build error messages

You can view Jekyll build error messages locally or configure a third-party service to display error messages after each commit.

Viewing Jekyll build error messages locally

To view Jekyll build errors locally, install Jekyll on your computer and run the jekyll build --safe command in the root of your GitHub Enterprise Pages repository. For more details on setting up and running Jekyll locally, see Using Jekyll with Pages.

Configuring a third-party service to display Jekyll build error messages

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

• Add a file named Gemfile (note that the "G" must be capitalized) to the root of your GitHub Enterprise Pages repository with the following content:

source 'https://rubygems.org'

gem 'github-pages'

• Configure your GitHub Enterprise Pages repository for the testing service of your choice. To set up Travis CI, for example, add a file named .travis.yml to the root of your GitHub Enterprise Pages repository with the following content:

language: ruby
script: "bundle exec jekyll build"

• You may need to activate your GitHub Enterprise Pages repository within the third-party testing service. For Travis, do this on your Travis CI profile page.