GitHub Actions による GitHub Pages への自動デプロイ

GitHub Actions の登場により GitHub Pages へのデプロイがとても簡単になりました。手順を書いた YAML ファイルを Push するだけでビルド・デプロイの CI/CD を構築できます。この記事では GitHub Actions を用いて GitHub Pages へのデプロイを自動化する方法を紹介します。

Hugo のブログ・サイトの場合

具体的には以下のような YAML ファイルをデフォルトブランチに .github/workflows/gh-pages.yml として Push するだけで GitHub Pages へのデプロイが始まり、サイトが公開されます。

.github/workflows/gh-pages.yml

name: GitHub Pages

on:
  push:
    branches:
      - main  # Set a branch name to trigger deployment
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.85.0'

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

一応補足しておくと GITHUB_TOKEN は GitHub Actions runner で自動生成されるトークンであり、 Personal Access Token ではないのでご注意を。何も設定は必要ありません。

使用している Actions

最新の情報は各 Action のリポジトリにて確認してください。Issue, Pull Request, GitHub Star など、フィードバックをお待ちしてます。

GitHub Pages Action

Hugo Setup Action

• GitHub Action Hero: Shohei Ueda - The GitHub Blog

GitHub Pages Action, Hugo Action, mdBook Action のメンテナーとして GitHub Blog で紹介していただきました。ありがとうございます。

User and Organization リポジトリの場合

username/username.github.io リポジトリの場合は master ブランチに GitHub Pages で公開するファイルを配置する必要がありますので、YAML ファイルを少し修正して Push する必要があります。 (2020-10-16 追記) 現在の GitHub Pages では任意のブランチをデプロイ対象として指定できるようになったため、User and Organization リポジトリでも gh-pages ブランチを GitHub Pages 用途で使うことが可能となりました。

その他 Static Site Generator の例

Hugo プロジェクトの例を既に紹介しましたが、他の静的サイトジェネレーターでも同様に使えます。

Node.js (JavaScript) 系

Node.js (JavaScript) 製の静的サイトジェネレーターの場合は以下のような YAML にすればオッケーです。依存関係は package.json と package-lock.json で管理されているものとします。

next.js, nuxt.js, gatsby, hexo, gitbook, vuepress, react-static, gridsome, etc.

Gatsby の例を以下記事で解説しています。

• Gatsby のサイトを GitHub Actions で GitHub Pages にデプロイ - Qiita

Vue.js, Nuxt.js の例を以下記事で解説しています。

• Vue Nuxt アプリを GitHub Actions で GitHub Pages にデプロイ - Qiita

React.js, Next.js の例を以下記事で解説しています。

• React Next アプリを GitHub Actions で GitHub Pages にデプロイ - Qiita

.github/workflows/gh-pages.yml

name: GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci
      - run: npm run build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

Python 系

Python 製の静的サイトジェネレーターの場合は以下のような YAML にすればオッケーです。依存関係は requirements.txt で管理されているものとします。

pelican, MkDocs, sphinx, etc.

.github/workflows/gh-pages.yml

name: GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.8'

      - name: Upgrade pip
        run: |
          # install pip=>20.1 to use "pip cache dir"
          python3 -m pip install --upgrade pip

      - name: Get pip cache dir
        id: pip-cache
        run: echo "::set-output name=dir::$(pip cache dir)"

      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: ${{ steps.pip-cache.outputs.dir }}
          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      - name: Install dependencies
        run: python3 -m pip install -r ./requirements.txt

      - run: mkdocs build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

mdBook (Rust)

GitHub Actions 上で Rust 製静的サイトジェネレーター mdBook を実行し、生成したサイトを GitHub Pages へデプロイするワークフローの例です。

name: GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v2
        with:
          mdbook-version: '0.4.8'
          # mdbook-version: 'latest'

      - run: mdbook build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book

Flutter Web

Flutter web project のワークフローの例です。

name: GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4

      - name: Setup Flutter
        run: |
          git clone https://github.com/flutter/flutter.git --depth 1 -b beta _flutter
          echo "${GITHUB_WORKSPACE}/_flutter/bin" >> ${GITHUB_PATH}

      - name: Install
        run: |
          flutter config --enable-web
          flutter pub get

      - name: Build
        run: flutter build web

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build/web

Elm

Elm のワークフロー例です。

name: GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '14'

      - name: Setup Elm
        run: npm install elm --global

      - name: Make
        run: elm make --optimize src/Main.elm

      - name: Move files
        run: |
          mkdir ./public
          mv ./index.html ./public/
        # If you have non-minimal setup with some assets and separate html/js files,
        # provide --output=<output-file> option for `elm make` and remove this step

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

github/personal-website

GitHub Pages built-in Jekyll を使う例です。

• github/personal-website - Code that'll help you kickstart a personal website that showcases your work as a software developer.

.github/workflows/github-pages.yml

name: GitHub Pages

on:
  push:
    branches:
      - master
  schedule:
    - cron: '24 */24 * * *'  # Once a day

jobs:
  deploy:
    runs-on: ubuntu-22.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./
          allow_empty_commit: true
          enable_jekyll: true
          cname: github.peaceiris.com

Swift Publish

Swift 製の静的サイトジェネレーター JohnSundell/Publish のワークフロー例です。

name: GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: macos-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/cache@v4
        with:
          path: |
            ~/Publish_build
            .build
          key: ${{ runner.os }}-spm-${{ hashFiles('**/Package.resolved') }}
          restore-keys: |
            ${{ runner.os }}-spm-

      - name: Setup JohnSundell/Publish
        run: |
          cd ${HOME}
          export PUBLISH_VERSION="0.7.0"
          git clone https://github.com/JohnSundell/Publish.git
          cd ./Publish && git checkout ${PUBLISH_VERSION}
          mv ~/Publish_build .build || true
          swift build -c release
          cp -r .build ~/Publish_build || true
          echo "${HOME}/Publish/.build/release" >> ${GITHUB_PATH}

      - run: publish-cli generate

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./Output

その他のオプションやサンプル

利用可能なオプションの定義は action.yml で確認できます。

(もしリクエストがあればオプションの日本語解説も頑張って書きます。)

最新の README.md を確認してください。

個人的に面白いと思った活用事例

fastai/fastpages

fastpages は Jupyter Notebook からブログを生成して GitHub Pages へデプロイできるツールであり、内部で peaceiris/actions-gh-pages@v3 を使っています。初期セットアップをガイドしてくれる Pull Request を発行してくれるなど、なかなか面白い GitHub Actions の使い方をしていて勉強になりました。

GitHub Pages にデプロイしない用途

• tokyo-metropolitan-gov/covid19
• codeforsapporo/covid19

東京都が始めて、北海道版もある新型コロナウイルス対策サイトですが、ここでも弊 Action を活用いただいています。最初見た時に GitHub Pages でサイトを公開している様子がなかったので、なぜ使っているのか疑問でしたが、どうやら「ビルドした成果物をブランチで共有する」という目的で使っているようです。

例えば publish_branch: production を指定しておき production ブランチに生成物を push するようにします。こうしておけば、デプロイ先に Netlify を利用する場合には production を公開ブランチとして指定することでビルドを省略できます。VPS やレンタルサーバーなどでサイトを公開する場合には定期的に git pull するだけで済むようになります。