Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/edricchan03/action-build-deploy-ghpages
GitHub Action to build and deploy a Jekyll site to GitHub Pages.
https://github.com/edricchan03/action-build-deploy-ghpages
github-actions github-pages jekyll
Last synced: about 1 month ago
JSON representation
GitHub Action to build and deploy a Jekyll site to GitHub Pages.
- Host: GitHub
- URL: https://github.com/edricchan03/action-build-deploy-ghpages
- Owner: EdricChan03
- License: mit
- Created: 2019-08-12T05:29:56.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-04-24T00:27:07.000Z (8 months ago)
- Last Synced: 2024-05-28T18:52:53.120Z (7 months ago)
- Topics: github-actions, github-pages, jekyll
- Language: Shell
- Size: 66.4 KB
- Stars: 9
- Watchers: 2
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/settings/tokens/new?scopes=public_repo,repo_deployment&description=Token%20for%20Deploy%20GitHub%20Pages%20GitHub%20Action) 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](#secrets-used) section for more info.)
This GitHub Action is licensed under the MIT license. View the [repository's `LICENSE` file for more information](https://github.com/EdricChan03/action-build-deploy-ghpages/blob/main/LICENSE).
## 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](https://github.com/orgs/community/discussions/25777#discussioncomment-3249229) and [#29](https://github.com/EdricChan03/action-build-deploy-ghpages/issues/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](https://help.github.com/articles/configuring-jekyll-plugins/#default-plugins), you don't have to use this action as GitHub should automatically build your Jekyll site.
From [Jekyll's documentation](https://jekyllrb.com/docs/github-pages/):
> 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](https://help.github.com/articles/configuring-jekyll-plugins/#default-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](https://github.com/EdricChan03/action-build-deploy-ghpages/issues/new) 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)](https://github.com/EdricChan03/action-build-deploy-ghpages/compare) 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](https://github.com/EdricChan03/action-build-deploy-ghpages/compare) 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](https://github.com/EdricChan03/action-build-deploy-ghpages/compare) with the suggestion)
---
## Usage
See [`action.yml`](./action.yml) for a list of all supported inputs.
### Secrets used
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 **(~~required~~ optional - no longer required as of 15 Feb 2020 - see this [GitHub Community post](https://github.community/t5/GitHub-Actions/Github-action-not-triggering-gh-pages-upon-push/m-p/46519/highlight/true#M6551) and [#13](https://github.com/EdricChan03/action-build-deploy-ghpages/issues/13) for more info)** | A valid personal access token (create one [here](https://github.com/settings/tokens/new?scopes=public_repo,repo_deployment&description=Token%20for%20Deploy%20GitHub%20Pages%20GitHub%20Action) with the scopes `public_repo` and `repo_deployment` enabled)
### Examples
#### Basic
```yml
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 info
```
Alternatively, you can target the latest `v3` version of the Action:
```yml
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:
```yml
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'
# ...
```
#### All inputs (with defaults)
> Note: Not all of the inputs below have default values - consult the [action file](./action.yml) for more info.
```yml
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/)
```