【完全版】GitHub ActionsでHugoを自動デプロイする仕組みを理解する

🚀 はじめに：この記事で学べること

本記事では、Hugo + GitHub Pages でブログを運用している初心者の方向けに、
GitHub Actions を使って自動デプロイする仕組みを、できるだけ分かりやすく解説します。

GitHub Actions が何をしているのか
Hugo のビルドがどのように自動化されるのか
gh-pages ブランチへ自動デプロイされる仕組み
実際に使えるワークフローのテンプレート

補足
「自動デプロイ」は、記事を更新するたびに手動で hugo → git push → gh-pages へ反映…という作業をなくすための仕組みです。

🧱 Step 1：GitHub Actions の基本を理解する

GitHub Actions は、GitHub が提供する 自動実行の仕組み（CI/CD） です。

🔧 何が自動化されるのか？

Hugo のインストール
サイトのビルド（hugo コマンド）
public/ の生成
gh-pages ブランチへのデプロイ

これらを YAMLファイル（ワークフロー） に書いておくことで、GitHub が自動で実行してくれます。

📁 Step 2：ワークフローの配置場所を知る

GitHub Actions の設定ファイルは、リポジトリ内の以下に置きます。

.github/workflows/deploy.yml

注意
ディレクトリ名 .github/workflows/ を間違えると、GitHub Actions が認識しません。

⚙️ Step 3：Hugo 自動デプロイ用ワークフローの例

以下は、Hugo サイトを GitHub Pages に自動デプロイする最小構成の例です。

name: Deploy Hugo site

on:
  push:
    branches:
      - main   # main ブランチに push されたら実行

jobs:
  build-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: "latest"   # Hugo のバージョン

      - name: Build
        run: hugo --minify         # サイトをビルド

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public    # Hugo の出力先
          publish_branch: gh-pages # デプロイ先ブランチ

🔍 このワークフローがやっていること

ステップ	内容
checkout	リポジトリの内容を取得
setup Hugo	Hugo をインストール
build	`hugo` を実行して `public/` を生成
deploy	`public/` を `gh-pages` に push

補足
peaceiris/actions-gh-pages は GitHub Pages へのデプロイで最もよく使われる Action です。

🏁 Step 4：GitHub Pages の設定を確認する

GitHub リポジトリの Settings → Pages を開き、以下のように設定します。

Source：Deploy from a branch
Branch：gh-pages / (root)

注意
gh-pages ブランチが存在しない場合、初回デプロイ後に自動生成されます。

🧪 Step 5：実際に動かしてみる

main ブランチに記事を追加
git push
GitHub Actions が自動でビルド
数十秒後、gh-pages にデプロイ
GitHub Pages が更新される

補足
Actions の実行ログは Actions タブ から確認できます。
エラーが出た場合は、どのステップで失敗したかを確認しましょう。

🧯 よくあるつまずき（チェックリスト）

.github/workflows/ の場所が正しいか
baseURL が公開URLと一致しているか
gh-pages ブランチが GitHub Pages の Source に設定されているか
Hugo のバージョン指定が正しいか
public/ が正しく生成されているか

📚 参考リンク

GitHub Actions 公式
- https://docs.github.com/actions
peaceiris/actions-hugo
- https://github.com/peaceiris/actions-hugo
peaceiris/actions-gh-pages
- https://github.com/peaceiris/actions-gh-pages
Hugo 公式ドキュメント
- https://gohugo.io/

🔧 拡張案（次にやると良いこと）

GitHub Actions のキャッシュ最適化
- Node.js や Hugo のキャッシュを使ってビルド高速化
マルチ環境デプロイ
- ステージング環境と本番環境を分ける
Lint / Link Checker の追加
- 記事の品質チェックを自動化
画像最適化パイプラインの導入
- WebP 生成やリサイズを自動化
PR 時のプレビュー生成
- Netlify や Cloudflare Pages と組み合わせてプレビューを自動生成

✅ まとめ

GitHub Actions を使えば、Hugo サイトのデプロイを完全自動化できる
ワークフローは .github/workflows/ に配置
hugo → public/ → gh-pages の流れを自動化するだけ
GitHub Pages の設定と合わせて使うと、更新がとても楽になる

🚀 はじめに：この記事で学べること#

🧱 Step 1：GitHub Actions の基本を理解する#

🔧 何が自動化されるのか？#

📁 Step 2：ワークフローの配置場所を知る#

⚙️ Step 3：Hugo 自動デプロイ用ワークフローの例#

🔍 このワークフローがやっていること#

🏁 Step 4：GitHub Pages の設定を確認する#

🧪 Step 5：実際に動かしてみる#

🧯 よくあるつまずき（チェックリスト）#

📚 参考リンク#

🔧 拡張案（次にやると良いこと）#

✅ まとめ#