MkDocsサイトを S3へデプロイする GitHub Actions ワークフローを作ってみる

2022.05.06

はじめに

MkDocs による静的サイトを S3バケットへデプロイする GitHubワークフローを作成してみました。 手順をまとめます。

下図にざっくりとした流れを記載しています。

img

MkDocsとは

MkDocs は静的サイトジェネレーターです。 ドキュメントのソースを Markdownで記述します。 ページ構成やテーマなどの設定は YAMLファイルで指定、 幅広いカスタマイズが可能です。 GitHub Pages や S3バケット(今回のターゲット)へデプロイして、 公開することもできます。

※MkDocs の詳しい使い方やチューニングについては以下記事を参照ください。

S3へのデプロイワークフローを作成する

※ Sphinx (静的サイトジェネレーター) ドキュメント を S3へデプロイしている以下ブログを大いに参考にしています。

S3バケットの作成

事前にデプロイ先の S3バケットを準備します。

GitHub リポジトリの作成

Getting Started - MkDocs どおりにサンプルドキュメントを作成、 これを GitHubリポジトリへプッシュしておきます。 (ローカルのテストで mkdocs build したときに作られる site/ ディレクトリは .gitignore に入れておくと良いでしょう)

(参考) ファイル構成は以下のようになりました。

$ tree -L 2
.
├── docs
│   ├── about.md
│   └── index.md
└── mkdocs.yml

mkdocs.yml

site_name: MkLorum
site_url: https://example.com/
nav:
    - Home: index.md
    - About: about.md
theme: readthedocs

GitHub OIDCプロバイダー設定

  • IDプロバイダーの作成
  • IAMロールの作成

を行います。 ここの設定は以下ブログによくまとまっています。そちらを参照ください。

IAMロールの権限は以下のとおりです。 (今回は検証のため、Action 部分は s3:* としています。 s3 sync で使用する権限に絞ることも可能です)

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::${S3バケット名}",
                "arn:aws:s3:::${S3バケット名}/*"
            ]
        }
    ]
}

GitHub ワークフロー作成

以下のようなワークフローを作成しました。

今回は手動実行とするために on: workflow_dispatch と記載しています。

.github/workflows/sync-mkdocs-build.yml

name: Sync Mkdocs build to S3
on: workflow_dispatch
env:
  BUCKET_NAME : "${バケット名}"
  AWS_REGION : "ap-northeast-1"
  AWS_ROLE_ARN: "arn:aws:iam::${AWSアカウントID}:role/${IAMロール名}"
permissions:
  id-token: write
  contents: read
jobs:
  Sync:
    runs-on: ubuntu-latest
    steps:
      - name: Git clone the repository
        uses: actions/checkout@v3

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: ${{ env.AWS_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}

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

      - name: Install MkDocs
        run: |
          pip install -U mkdocs

      - name: Build
        run: |
          mkdocs build

      - name: Sync html to s3
        run: |
          aws s3 sync ./site s3://${{ env.BUCKET_NAME }}/site --delete --quiet

大枠はこちらの Sphinx ブログ とほぼ同じです。 mkdocs の場合はビルドコマンドが mkdocs build 、 ビルドしたときの成果物が (デフォルトで) site となります。

ワークフローを実行する

[リポジトリ > Actions] から作成したワークフローを手動実行してみます。

img

実行結果は以下のようになります。各ステップが成功していること確認できました。

img

S3バケットを確認すると site/ 配下にオブジェクトがデプロイされていますね。

img

S3バケットの静的ウェブホスティングを有効にしてアクセスもできました。

img

おわりに

MkDocsサイトを S3へデプロイする GitHub Actions ワークフローを作ってみました。

静的サイトのコンテンツ格納先として S3バケットはよく使われます。 その S3バケットへのデプロイを手軽に実現できました。 IAMロールでのアクセスも便利でいいですね。

参考