160 lines
4.4 KiB
Markdown
160 lines
4.4 KiB
Markdown
[](https://github.com/peaceiris/actions-gh-pages/blob/master/LICENSE)
|
|
[](https://github.com/peaceiris/actions-gh-pages/releases/latest)
|
|
[](https://github.com/peaceiris/actions-gh-pages/releases)
|
|
[](https://github.com/peaceiris/actions-gh-pages/actions)
|
|
[](https://hub.docker.com/r/peaceiris/gh-pages)
|
|
|
|
<img width="400" alt="GitHub Actions for deploying to GitHub Pages with Static Site Generators" src="./images/ogp.svg">
|
|
|
|
|
|
|
|
## GitHub Actions for deploying to GitHub Pages
|
|
|
|
A GitHub Action to deploy your static site to GitHub Pages with [Static Site Generators] (Hugo, MkDocs, Gatsby, GitBook, etc.)
|
|
|
|
[Static Site Generators]: https://www.staticgen.com/
|
|
|
|
|
|
|
|
## Getting started
|
|
|
|
### (1) Add ssh deploy key
|
|
|
|
Generate your deploy key with the following command.
|
|
|
|
```sh
|
|
ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
|
|
# You will get 2 files:
|
|
# gh-pages.pub (public key)
|
|
# gh-pages (private key)
|
|
```
|
|
|
|
Next, Go to **Repository Settings**
|
|
|
|
- Go to **Deploy Keys** and add your public key with the **Allow write access**
|
|
- Go to **Secrets** and add your private key as `ACTIONS_DEPLOY_KEY`
|
|
|
|
### (2) Create `.github/workflows/gh-pages.yml`
|
|
|
|
An example yaml file with Hugo action.
|
|
|
|
- [peaceiris/actions-hugo: GitHub Actions for Hugo extended](https://github.com/peaceiris/actions-hugo)
|
|
|
|
|
|
|
|
|
|
```yaml
|
|
name: github pages
|
|
|
|
on:
|
|
push:
|
|
branches:
|
|
- master
|
|
|
|
jobs:
|
|
build-deploy:
|
|
runs-on: ubuntu-18.04
|
|
steps:
|
|
- uses: actions/checkout@master
|
|
|
|
- name: build
|
|
uses: peaceiris/actions-hugo@v0.58.0
|
|
with:
|
|
args: --gc --minify --cleanDestinationDir
|
|
|
|
- name: deploy
|
|
uses: peaceiris/actions-gh-pages@v2.1.0
|
|
env:
|
|
ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
|
|
PUBLISH_BRANCH: gh-pages
|
|
PUBLISH_DIR: ./public
|
|
```
|
|
|
|
### Options
|
|
|
|
#### Pull action image from Docker Hub
|
|
|
|
You can pull a public docker image from Docker Hub.
|
|
By pulling docker images, you can reduce the overall execution time of your workflow. In addition, `latest` tag is provided.
|
|
|
|
```diff
|
|
- uses: peaceiris/actions-gh-pages@v2.1.0
|
|
+ uses: docker://peaceiris/gh-pages:v2.1.0
|
|
```
|
|
|
|
- [peaceiris/gh-pages - Docker Hub](https://hub.docker.com/r/peaceiris/gh-pages)
|
|
|
|
```diff
|
|
- uses: peaceiris/actions-hugo@v0.58.0
|
|
+ uses: docker://peaceiris/gha-hugo:v0.58.0
|
|
```
|
|
|
|
- [peaceiris/gha-hugo - Docker Hub](https://hub.docker.com/r/peaceiris/gha-hugo)
|
|
|
|
### `GITHUB_TOKEN`
|
|
|
|
> **NOTES**: This action supports `GITHUB_TOKEN` but it has some problems to deploy to GitHub Pages. See #9
|
|
|
|
```diff
|
|
- ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
|
|
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
```
|
|
|
|
|
|
|
|
## Examples
|
|
|
|
### MkDocs
|
|
|
|
|
|
|
|
```yaml
|
|
name: github pages
|
|
|
|
on:
|
|
push:
|
|
branches:
|
|
- master
|
|
|
|
jobs:
|
|
build-deploy:
|
|
runs-on: ubuntu-18.04
|
|
steps:
|
|
- uses: actions/checkout@v1
|
|
|
|
- name: Set up Python
|
|
uses: actions/setup-python@v1
|
|
with:
|
|
python-version: '3.6'
|
|
architecture: 'x64'
|
|
|
|
- name: Install dependencies
|
|
run: |
|
|
pip install --upgrade pip
|
|
pip install -r ./requirements.txt
|
|
|
|
- name: Build with MkDocs
|
|
run: mkdocs build
|
|
|
|
- name: Deploy to GitHub Pages
|
|
uses: peaceiris/actions-gh-pages@v2.1.0
|
|
env:
|
|
ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
|
|
PUBLISH_BRANCH: gh-pages
|
|
PUBLISH_DIR: ./site
|
|
```
|
|
|
|
|
|
|
|
## License
|
|
|
|
- [MIT License - peaceiris/actions-gh-pages]
|
|
|
|
[MIT License - peaceiris/actions-gh-pages]: https://github.com/peaceiris/actions-gh-pages/blob/master/LICENSE
|
|
|
|
|
|
|
|
## About the author
|
|
|
|
- [peaceiris's homepage](https://peaceiris.com/)
|