Razl-Dazl

eyecatch
© 2014 Steve Francia

Hugo用テーマとMarkdownファイルのリポジトリを分離して管理する

Posted at — 2024-10-03

Hugoでウェブサイトを生成する際、Markdownファイルはcontent/以下に配置することになりますが、このcontent/以下のファイルを別のリポジトリで管理するようにしました

分離することにより、Hugoでのビルド時には都度ファイルの配置をもとに戻す必要がありますが、ここはGitHub Actionsで自動化する事としました

元々HugoでのビルドはGItHub Actionsで行っていた為、構成はそれをベースに改良しました

元々の構成は以下↓

改良後はこちら


1つ目のWorkFlowファイル作成

元々のリポジトリからcontent/以下を削除し、こちらをテーマや設定ファイルのリポジトリとします

そして.github/workflowsの下にGitHub Actions用のYAMLファイルを作成します(ファイル名は適当でいいけどworkflow.ymlとします)

Workflowファイルで定義する処理は

  1. 自分のリポジトリをチェックアウト
  2. Markdownを管理するリポジトリを、パスを指定してClone
  3. Hugoでビルド
  4. ビルドしたファイル達を別のリポジトリへPush
name: GitHub Pages Build with Hugo

on:
  push:
  repository_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - name: Checkout theme and config files
        uses: actions/checkout@v3
        with:
          submodules: true 
          fetch-depth: 0

      - name: Checkout Markdown files
        uses: actions/checkout@v3
        with:
          repository: username/repository_name #各自のユーザー名/リポジトリ
          path: ./content/posts # セクション単位での管理の為にサブディレクトリを指定
          token: ${{ secrets.ACCESS_TOKEN }}

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: latest
          
      - name: Build
        run: hugo --minify
        
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          external_repository: username/username.github.io #各自のユーザー名
          PUBLISH_BRANCH: main
          publish_dir: username.github.io #Hugoの設定ファイルで指定したパス
          personal_token: ${{ secrets.ACCESS_TOKEN }}

私はMarkdownファイルをHugoでのセクション単位(content/以下のサブディレクトリ単位)で管理するためにpath: ./content/postsとしましたがここは各自の環境のに合わせてください

またデプロイ時のpublish_dirは、Hugoの設定ファイルのpublishDirで設定したフォルダを指定します

hugo-versionは最新になるようlatestを指定していますが、テーマの対応が追いつかない場合にビルドエラーを起こす可能性もあります 必要に応じてバージョンを固定する措置も要検討

secrets.ACCESS_TOKENはリポジトリの操作の際に必要ですが、値は後ほど定義します

このリポジトリのファイル配置は以下のようになるはず

repository/
  ├ .github/
  │ └ workflows/
  │   └ workflow.yml
  ├ content/ #中身は分離するので消す
  ├ layouts/
  ├ themes/
  ├ static/
  └ config.yml

2つ目のWorkFlowファイル作成

markdownのファイルだけを分離して新たにリポジトリを作成し、Workflowファイルを定義します

こちらでは直接処理を記述せず、1つめのWorkflowファイルを呼び出すよう定義します

GitHub ActionsではREST API経由での発火が可能ですので、それを用いて処理を記述します

name: GitHub Pages Trigger

on:
  push:
  workflow_dispatch:

jobs:
  job01:
    runs-on: ubuntu-latest
    steps:
      - name: exec REST API
        run: |
          curl \
            -X POST \
            -H "Accept: application/vnd.github.v3+json" \
            -H "Authorization: token ${{ secrets.ACCESS_TOKEN }}" \
            https://api.github.com/repos/your_username/repository_name/dispatches \
            -d '{"event_type":"workflow_dispatch"}' \
            -s \
            -w "%{http_code}"

URLのyour_username/repository_nameは各自のものに置き換えます

secrets.ACCESS_TOKENは別途定義します

またHTTPステータスコードを出力するようにしていますが、これは後のログ確認時に使用するために追加しました

repository/
  ├ .github/
  │ └ workflows/
  │   └ workflow.yml
  ├ foobar1.md
  ├ foobar2.md
  └ foobar3.md

アクセストークンを定義する

予めGitHubの設定からPersonal Access Tokenを発行し値をメモしておきます

GitHub上の各リポジトリのSettings > SecurityのSecrets and variables > Actions を選択、[New repository secret] からアクセストークンの値を定義します

Secretの欄にメモしてきた値を入力します

リポジトリ単位での設定値となるのでこれを各リポジトリで行います


実行ログの確認

各設定ファイルをCommitしてPushしたら、各リポジトリのActionsから実行結果を確認します

正常に処理を終えたら緑のチェックマークが付きます

問題があった場合はここからログを確認して原因を探ります

ちなみに、2つ目のWorkflowファイルで定義したHTTPステータスコードの出力はここで役立ちます

2つ目のWorkflowファイルではcurlの処理の実行さえ終了すれば正常終了扱いとなるため、HTTPステータスコードが401や404であった場合も緑のチェックマークが付いてしまいます

呼出先のWorkflowがうまく実行されない場合は、curlの出力結果も参考にしてみて下さい


参考

Author@zakuro

Mastodon: 396@vivaldi.net