GitHub Pages 사이트에 대한 Jekyll 빌드 오류 정보

Jekyll이 로컬로 또는 GitHub Enterprise Cloud에서 GitHub Pages 사이트를 빌드하는 동안 오류가 발생하면 자세한 정보가 포함된 에러 메시지를 받게 됩니다.

누가 이 기능을 사용할 수 있나요?

GitHub Pages은(는) 조직의 GitHub Free 및 GitHub Free이(가) 있는 퍼블릭 리포지토리와 GitHub Pro, GitHub Team, GitHub Enterprise Cloud 및 GitHub Enterprise Server의 퍼블릭 및 프라이빗 리포지토리에서 사용할 수 있습니다. 자세한 내용은 “GitHub의 플랜”를 참조하세요.

GitHub Pages은(는) 이제 GitHub Actions을(를) 사용하여 Jekyll 빌드를 실행합니다. 빌드의 원본으로 분기를 사용하는 경우 기본 제공 Jekyll 워크플로를 사용하려면 리포지토리에서 GitHub Actions을(를) 사용하도록 설정해야 합니다. 또는 GitHub Actions을(를) 사용할 수 없거나 사용하지 않도록 설정한 경우 원본 분기의 루트에 .nojekyll 파일을 추가하면 Jekyll 빌드 프로세스를 무시하고 콘텐츠를 직접 배포합니다. GitHub Actions 사용에 대한 자세한 내용은 "리포지토리에 대한 GitHub Actions 설정 관리"을 참조하세요.

이 문서의 내용

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

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 "Re-running workflows and jobs."

Viewing Jekyll build error messages locally

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 Enterprise Cloud. For more information, see "Testing your GitHub Pages site locally with Jekyll."

Viewing Jekyll build error messages in your pull request

If you are publishing from a branch, when you create a pull request to update your publishing source on GitHub Enterprise Cloud, you can see build error messages on the Checks tab of the pull request. For more information, see "About 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."

Viewing Jekyll build errors by email

If you are publishing from a branch, when you push changes to your publishing source on GitHub Enterprise Cloud, 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."

Viewing Jekyll build error messages in your pull request with a third-party CI service

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

  1. 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`

  2. 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"

  3. You may need to activate your repository with the third-party testing service. For more information, see your testing service's documentation.