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

Table of Contents

• Getting started
  • (1) Add ssh deploy key
  • (2) Create .github/workflows/gh-pages.yml
    • Repository type - Project
    • Repository type - User and Organization
  • Options
    • Pull action image from Docker Hub
    • PERSONAL_TOKEN
    • GITHUB_TOKEN
• Examples
  • MkDocs
• License
• About the author

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

Repository type - Project

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

The above example is for Project Pages sites. (<username>/<project_name> repository)

Repository type - User and Organization

For User and Organization Pages sites (<username>/<username>.github.io repository), we have to set master branch to PUBLISH_BRANCH.

on:
  push:
    branches:
    - source  # default branch

PUBLISH_BRANCH: master  # deploying branch

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

Generate 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