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.)

Getting started

(1) Add ssh deploy key

Generate your deploy key with the following command.

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

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.2.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.

- uses: peaceiris/actions-gh-pages@v2.2.0
+ uses: docker://peaceiris/gh-pages:v2.2.0

• peaceiris/gh-pages - Docker Hub

- uses: peaceiris/actions-hugo@v0.58.0
+ uses: docker://peaceiris/gha-hugo:v0.58.0

• peaceiris/gha-hugo - Docker Hub

PERSONAL_TOKEN

Create a personal access token (repo) and add it to Secrets as PERSONAL_TOKEN, it works as well as ACTIONS_DEPLOY_KEY.

- ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+ PERSONAL_TOKEN: ${{ secrets.PERSONAL_TOKEN }}

GITHUB_TOKEN

NOTES: This action supports GITHUB_TOKEN but it has some problems to deploy to GitHub Pages. See #9

- ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Examples

MkDocs

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.2.0
      env:
        ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
        PUBLISH_BRANCH: gh-pages
        PUBLISH_DIR: ./site

License

• MIT License - peaceiris/actions-gh-pages

About the author

• peaceiris's homepage