MkDocs で作ったドキュメントを GitHub Actions を使って GitHub Pages にデプロイしよう

MkDocs は、GitHub Pages にデプロイするために
“gh-deploy” というコマンドがあります。
このコマンドは GitHub Actions で実行しようとすると、
リポジトリーへのプッシュが認可されず 403 エラーになっていまいます。

そこで、この問題を解決するため、
「GitHub Pages action」という Action を使いましょう。

前提と用語
- デプロイ元リポジトリー
- デプロイ先リポジトリー
デプロイ処理の設定手順

前提と用語

まず、説明のための言葉を整理します。

デプロイ元リポジトリー

MkDocs のプロジェクトのためのリポジトリーを指します。
GitHub Actions でデプロイを行います。

デプロイ先リポジトリー

MkDocs のビルド結果をデプロイして
GitHub Pages で公開するためのリポジトリーを指します。

デプロイ元リポジトリーと同じリポジトリーにすることもできますが、
できる限り別のリポジトリーにすることをお奨めします。

同じリポジトリーにすると
静的ファイルのコミットによりリポジトリーの容量が増加し、
CI / CD の速度の低下等の影響が出ることが考えられます。

GitHub Pages サイトには以下の 3 種類があります:

プロジェクト
ユーザー
Organization

今回の例では、プロジェクトのリポジトリーに対してデプロイを行います。

参考: GitHub Pages について – GitHub ヘルプ

デプロイ処理の設定手順

手順

1. デプロイ先リポジトリーを準備します

デプロイ先リポジトリーを
デプロイ元リポジトリーと別のリポジトリーにしたい場合、
デプロイ先リポジトリーとして、新規リポジトリーを作成します。

ここで、README.md, .gitignore, LICENSE 等を作成しないように注意します。
リポジトリー名は自由です。

2. デプロイ先リポジトリーの所有者の個人用アクセストークンを取得します

GitHub のページ右上 [プロフィール画像] → [Settings]

ページ左側 [Developer settings] をクリック

[Personal access tokens] → [Generate new token] をクリック

発行の HMTL フォームで、[note] は、
後から見て用途が思い出せるような文字列を入力しておきます。
たとえば、次のように入力します:

Deploy docs of mkdocs-hello-world

公開リポジトリーの場合は [public_repo] に、
非公開リポジトリーの場合は [repo] にチェックを入れます。

参考:
コマンドライン用の個人アクセストークンを作成する – GitHub ヘルプ
 Understanding scopes for OAuth Apps | GitHub Developer Guide

そして [Generate token] ボタンをクリックします。

表示された文字列をパスワードマネージャー等に保存しておきます。

3. 個人用アクセストークンをデプロイ元リポジトリーの Secret に登録します

[Settings] → [Secrets] → [New secrets]

新規作成した個人用アクセストークンを “PERSONAL_TOKEN” として登録します。

4. デプロイ元リポジトリーにデプロイ用 GitHub Actions ワークフローを追加します

「GitHub Pages action」の README.md に
MkDocs の場合の実装例が掲載されています。

キャッシュに関する実装などを省いて最低限の実装にすると、
次のようなコードになります:

# この例では
# master ブランチにプッシュされたときに実行される設定にしています。
# GitHub Flow などで master ブランチにマージされる度にデプロイされます。
# 必要に応じてタグのプッシュなどに変更します。
on:
  push:
    branches:
      - master
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: '3.8'
      # Pipenv でパッケージ管理している場合を想定しています。
      - run: python -m pip install pipenv
      # Pipfile.lock を Git 管理に含めている場合を想定しています。
      - run: python -m pipenv sync --dev
      # まず、ビルドします。
      - run: python -m pipenv run mkdocs build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.PERSONAL_TOKEN }}
          # デプロイ元リポジトリーとデプロイ先が異なる場合、
          # external_repository を指定します。
          external_repository: github-user-name/github-repository-name
          # publish_branch を指定しない場合、
          # gh-pages ブランチにデプロイされます。
          publish_branch: master
          publish_dir: ./site