Help us understand the problem. What is going on with this article?

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

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

GitHub Actions による GitHub Pages への自動デプロイのためのアクション

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

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

.github/workflows/gh-pages.yml
name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.72.0'

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

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

上記は GitHub プロジェクトリポジトリ (名称が username/project_name 形式のリポジトリのこと) で Hugo を使って生成したブログ・サイトを GitHub Pages で公開する例です。

使用している Actions

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

GitHub Actions による GitHub Pages への自動デプロイのためのアクション

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

User and Organization リポジトリの場合

username/username.github.io リポジトリの場合は master ブランチに GitHub Pages で公開するファイルを配置する必要がありますので、YAML ファイルを少し修正して Push する必要があります。

例えば source ブランチを作ってデフォルトブランチとして利用し、そこでソースとなる Markdown ファイルなどを管理する場合の YAML ファイルは以下のようになります。

.github/workflows/gh-pages.yml
on:
  push:
    branches:
      - source  # default branch

publish_branch: master  # deploying branch

その他 Static Site Generator の例

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

Node.js (JavaScript) 系

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

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

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

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

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

.github/workflows/gh-pages.yml
name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: '12.x'

      - name: Cache dependencies
        uses: actions/cache@v1
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      - run: npm ci
      - run: npm run build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        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:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup Python
        uses: actions/setup-python@v1
        with:
          python-version: '3.6'
          architecture: 'x64'

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

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

      - run: mkdocs build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

mdBook (Rust)

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

name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

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

      - run: mdbook build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book

Flutter Web

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

name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

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

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

      - name: Build
        run: flutter build web

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build/web

Elm

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

name: github pages

on:
  push:
    branches:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup Node
        uses: actions/setup-node@v1
        with:
          node-version: '12.x'

      - 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@v3
        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-18.04
    steps:
      - uses: actions/checkout@v2
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        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:
      - master

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2

      - name: Setup JohnSundell/Publish
        run: |
          cd ${HOME}
          git clone --depth=1 https://github.com/JohnSundell/Publish.git
          cd ./Publish
          swift build -c release
          echo "::add-path::${HOME}/Publish/.build/release"

      - run: publish-cli generate

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        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 にデプロイしない用途

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

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

peaceiris
Hugo ʕ◔ϖ◔ʔ, Python, Deep Learning, Computer Vision, こっち https://peaceiris.com/ に引っ越しました。今後 Qiita への新規投稿はしませんが記事のメンテはします。
https://peaceiris.com/
admin-guild
「Webサービスの運営に必要なあらゆる知見」を共有できる場として作られた、運営者のためのコミュニティです。
https://admin-guild.slack.com
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした