Deploy to GitHub Pages

A GitHub Action that builds and deploys a Jekyll site to GitHub Pages.

Notes

This GitHub Action requires a GitHub personal access token to deploy commits. To create one, click here and specify the GH_PAGES_TOKEN environment variable in your GitHub repository's Secrets. (Note: You no longer have to create a PAT: see the Secrets used section for more info.)

This GitHub Action is licensed under the MIT license. View the repository's LICENSE file for more information.

Known issues

Error: Container action is only supported on Linux

This is because this GitHub Action is a Docker container action which appears to currently not be supported on environments other than Linux. For more information, see this GitHub Community discussion and #29.

FAQ

Should you use this Action?

If the Jekyll site you're building doesn't require any external plugins outside of the plugins specified on GitHub Pages' whitelisted plugins, you don't have to use this action as GitHub should automatically build your Jekyll site.

From Jekyll's documentation:

Your site is automatically generated by GitHub Pages when you push your source files. Note that GitHub Pages works equally well for regular HTML content, simply because Jekyll treats files without front matter as static assets. So if you only need to push generated HTML, you’re good to go without any further setup.

As for the "external plugins" portion, here's a quote from the same documentation:

Note that GitHub Pages runs in safe mode and only allows a set of whitelisted plugins.

Otherwise, if you're using plugins that are not in the list of whitelisted plugins, you may use this GitHub Action to build your Jekyll site.

How can I help?

If you have a bug report or feature request, you can open a new issue detailing your report/request.

Make sure to include the following information:

• For bug reports:
  • The version of the GitHub Action that you're using
  • The stacktrace of the issue (if any)
  • (Optionally, if the report only requires a simple fix, you may also submit a pull request (PR) with the fix)
• For feature requests:
  • The version of the GitHub Action that you're using
  • Benefits of implementing the feature
  • (Optionally, you can also submit a PR alongside it)
  • Include any breaking changes that this feature would introduce, if any
• For documentation suggestions:
  • A link to the documentation that you would like to suggest changes to
  • What benefits it would bring if the suggestion was implemented
  • (Optionally, you can also submit a PR with the suggestion)

Usage

See action.yml for a list of all supported inputs.

Secrets used

This script needs the following secrets:

Examples

Basic

steps:
  - uses: actions/checkout@v2
  - uses: EdricChan03/action-build-deploy-ghpages@v3.1.0
    with:
      github_token: ${{ secrets.GITHUB_TOKEN }}
      # gh_pages_token: ${{ secrets.GH_PAGES_TOKEN }} No longer needed - see https://github.community/t5/GitHub-Actions/Github-action-not-triggering-gh-pages-upon-push/m-p/46519/highlight/true#M6551 for more info

Alternatively, you can target the latest v3 version of the Action:

steps:
  - uses: actions/checkout@v2
  - uses: EdricChan03/action-build-deploy-ghpages@v3
    with:
      github_token: ${{ secrets.GITHUB_TOKEN }} # Or ${{ github.token }}
      # gh_pages_token: ${{ secrets.GH_PAGES_TOKEN }}

Environment variables (v1)

v2+ of this GitHub Action also supports the former environment variables in v1 of the action:

steps:
  - uses: actions/checkout@v2
  - uses: EdricChan03/action-build-deploy-ghpages@v3.1.0
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Or ${{ github.token }}
      # GH_PAGES_TOKEN: ${{ secrets.GH_PAGES_TOKEN }}
      OVERRIDE_GH_PAGES_BRANCH: 'true'
      # ...

All inputs (with defaults)

Note: Not all of the inputs below have default values - consult the action file for more info.

steps:
  - uses: actions/checkout@v2
  - uses: EdricChan03/action-build-deploy-ghpages@v3.1.0
    with:
      github_token: ${{ secrets.GITHUB_TOKEN }} # The GitHub installation token. Note: You can also use ${{ github.token }}
      # gh_pages_token: ${{ secrets.GH_PAGES_TOKEN }} # Note: You have to create this yourself - see the "Secrets used" section above for more info (This input does not have a default value - you have to supply this yourself) (As of 15 Feb 2020, this is no longer needed - see https://github.community/t5/GitHub-Actions/Github-action-not-triggering-gh-pages-upon-push/m-p/46519/highlight/true#M6551)
      gh_pages_branch: 'gh-pages' # The GitHub Pages branch to deploy the site to
      gh_pages_dist_folder: '_site' # The folder to build the site to
      gh_pages_commit_message: 'Deploy commit $GITHUB_SHA\n\nAutodeployed using $GITHUB_ACTION in $GITHUB_WORKFLOW' # The commit message to use when deploying the site
      jekyll_build_opts: '' # Options to pass to the Jekyll build command.
      remote_repo: 'https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git' # The repository to deploy the site to
      committer_username: '$GITHUB_ACTOR' # The username to use for the committer of the commit
      committer_email: '${GITHUB_ACTOR}@users.noreply.github.com' # The email to use for the committer of the commit
      git_force: 'true' # Whether to use the --force flag when pushing the commit
      override_gh_pages_branch: 'false' # Whether to override the gh-pages branch on push
      gh_pages_add_no_jekyll: 'true' # Whether to add the .nojekyll file to the deployed site
      skip_deploy: 'false' # Whether to skip deployment after a successful build.
      show_bundle_log: 'false' # Whether to show detailed logs from bundle install command. Useful for debugging broken builds.
      bundler_version: '' # A specific version of Bundler to be used.
      jekyll_env: 'production' # The Jekyll environment to use when building the site. (See https://jekyllrb.com/docs/configuration/environments/)