A GitHub Action that builds and deploys a Jekyll site to GitHub Pages.
This GitHub Action requires a GitHub personal access token to deploy commits. To create one, click here and specify the (Note: You no longer have to create a PAT: see the Secrets used section for more info.)GH_PAGES_TOKEN environment variable in your GitHub repository's Secrets.
This GitHub Action is licensed under the MIT license. View the repository's LICENSE file for more information.
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.
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
safemode 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.
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)
See action.yml for a list of all supported inputs.
This script needs the following secrets:
| Name | Description | Allowed values |
|---|---|---|
GITHUB_TOKEN |
Specifies the GitHub installation token. | A valid GitHub installation token. (Note: GitHub already creates one for you by default - you just need to manually specify this token with ${{ secrets.GITHUB_TOKEN }} or ${{ github.token }} in your workflow file.) |
GH_PAGES_TOKEN |
Specifies the personal access token to use to request a build request ( |
A valid personal access token (create one here with the scopes public_repo and repo_deployment enabled) |
steps:
- uses: actions/checkout@v2
- uses: EdricChan03/[email protected]
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 infoAlternatively, 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 }}v2+ of this GitHub Action also supports the former environment variables in v1 of the action:
steps:
- uses: actions/checkout@v2
- uses: EdricChan03/[email protected]
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Or ${{ github.token }}
# GH_PAGES_TOKEN: ${{ secrets.GH_PAGES_TOKEN }}
OVERRIDE_GH_PAGES_BRANCH: 'true'
# ...Note: Not all of the inputs below have default values - consult the action file for more info.
steps:
- uses: actions/checkout@v2
- uses: EdricChan03/[email protected]
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/)