MkDocsサイトを S3へデプロイする GitHub Actions ワークフローを作ってみる
この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
はじめに
MkDocs による静的サイトを S3バケットへデプロイする GitHubワークフローを作成してみました。 手順をまとめます。
下図にざっくりとした流れを記載しています。
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
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 と記載しています。
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] から作成したワークフローを手動実行してみます。
実行結果は以下のようになります。各ステップが成功していること確認できました。
S3バケットを確認すると site/ 配下にオブジェクトがデプロイされていますね。
S3バケットの静的ウェブホスティングを有効にしてアクセスもできました。
おわりに
MkDocsサイトを S3へデプロイする GitHub Actions ワークフローを作ってみました。
静的サイトのコンテンツ格納先として S3バケットはよく使われます。 その S3バケットへのデプロイを手軽に実現できました。 IAMロールでのアクセスも便利でいいですね。
