2019-05-21 21:53:54 +00:00
[![license ](https://img.shields.io/github/license/peaceiris/actions-gh-pages.svg )](https://github.com/peaceiris/actions-gh-pages/blob/master/LICENSE)
[![release ](https://img.shields.io/github/release/peaceiris/actions-gh-pages.svg )](https://github.com/peaceiris/actions-gh-pages/releases/latest)
[![GitHub release date ](https://img.shields.io/github/release-date/peaceiris/actions-gh-pages.svg )](https://github.com/peaceiris/actions-gh-pages/releases)
2019-08-21 19:58:58 +00:00
[![GitHub Actions status ](https://github.com/peaceiris/actions-gh-pages/workflows/docker%20image%20ci/badge.svg )](https://github.com/peaceiris/actions-gh-pages/actions)
2019-09-02 10:23:36 +00:00
[![Docker Hub Build Status ](https://img.shields.io/docker/cloud/build/peaceiris/gh-pages.svg )](https://hub.docker.com/r/peaceiris/gh-pages)
2019-05-21 21:53:54 +00:00
< 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
2019-09-05 14:07:49 +00:00
### (1) Add ssh deploy key
2019-05-21 21:53:54 +00:00
2019-09-05 14:07:49 +00:00
Generate your deploy key with the following command.
```sh
2019-09-05 15:50:59 +00:00
ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
2019-09-05 14:07:49 +00:00
# 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.
2019-05-21 21:53:54 +00:00
- [peaceiris/actions-hugo: GitHub Actions for Hugo extended ](https://github.com/peaceiris/actions-hugo )
2019-05-26 21:25:57 +00:00
![peaceiris/actions-hugo latest version ](https://img.shields.io/github/release/peaceiris/actions-hugo.svg?label=peaceiris%2Factions-hugo )
![peaceiris/actions-gh-pages latest version ](https://img.shields.io/github/release/peaceiris/actions-gh-pages.svg?label=peaceiris%2Factions-gh-pages )
2019-08-21 17:48:35 +00:00
```yaml
2019-08-21 20:02:54 +00:00
name: github pages
2019-08-21 17:48:35 +00:00
on:
push:
branches:
- master
jobs:
build-deploy:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@master
2019-09-05 14:07:49 +00:00
2019-08-21 17:48:35 +00:00
- name: build
2019-09-05 14:07:49 +00:00
uses: peaceiris/actions-hugo@v0.58.0
2019-08-21 17:48:35 +00:00
with:
args: --gc --minify --cleanDestinationDir
2019-09-05 14:07:49 +00:00
2019-08-21 17:48:35 +00:00
- name: deploy
2019-09-07 19:28:37 +00:00
uses: peaceiris/actions-gh-pages@v2.2.0
2019-08-21 17:48:35 +00:00
env:
2019-09-05 14:07:49 +00:00
ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
2019-08-21 17:48:35 +00:00
PUBLISH_BRANCH: gh-pages
PUBLISH_DIR: ./public
2019-05-21 21:53:54 +00:00
```
2019-09-05 14:07:49 +00:00
### 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
2019-09-07 19:28:37 +00:00
- uses: peaceiris/actions-gh-pages@v2.2.0
+ uses: docker://peaceiris/gh-pages:v2.2.0
2019-09-05 14:07:49 +00:00
```
- [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 )
2019-09-07 19:24:03 +00:00
#### `PERSONAL_TOKEN`
[Create a personal access token (`repo`) ](https://github.com/settings/tokens ) and add it to Secrets as `PERSONAL_TOKEN` , it works as well as `ACTIONS_DEPLOY_KEY` .
```diff
- ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+ PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }}
```
2019-09-05 16:16:44 +00:00
#### `GITHUB_TOKEN`
2019-09-05 14:07:49 +00:00
> **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 }}
```
2019-05-21 21:53:54 +00:00
2019-05-25 21:32:29 +00:00
## Examples
### MkDocs
2019-05-26 21:25:57 +00:00
![peaceiris/actions-gh-pages latest version ](https://img.shields.io/github/release/peaceiris/actions-gh-pages.svg?label=peaceiris%2Factions-gh-pages )
2019-09-05 14:07:49 +00:00
```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
2019-09-07 19:28:37 +00:00
uses: peaceiris/actions-gh-pages@v2.2.0
2019-09-05 14:07:49 +00:00
env:
ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
PUBLISH_BRANCH: gh-pages
PUBLISH_DIR: ./site
2019-05-25 21:32:29 +00:00
```
2019-05-21 21:53:54 +00:00
## License
2019-09-02 09:35:05 +00:00
- [MIT License - peaceiris/actions-gh-pages]
2019-05-21 21:53:54 +00:00
[MIT License - peaceiris/actions-gh-pages]: https://github.com/peaceiris/actions-gh-pages/blob/master/LICENSE
2019-05-22 12:11:01 +00:00
## About the author
- [peaceiris's homepage ](https://peaceiris.com/ )