コンテンツにスキップ

GitHub Pages から Cloudflare Pages への移行

GitHub Pages で公開していた MkDocs のサイトを Cloudflare Pages に移行する。 GitHub リポジトリと連携することで、Git push による自動ビルド・デプロイを実現する。 また、ブランチを利用したプレビュー環境と Cloudflare Access によるアクセス制限についても紹介する。

1. はじめに

これまで MkDocs で作成したサイトは、GitHub Pages を利用して公開していた。

GitHub Pages では、mkdocs gh-deploy コマンドを実行することで、ビルドしたサイトを公開できる。

今回は、公開先を Cloudflare Pages に変更する。

Cloudflare Pages では GitHub リポジトリと連携することで、ソースコードを push するだけで自動的にビルド・デプロイできる。

また、プレビュー環境を利用すれば、本番公開する前にサイトの表示を確認できる。

2. 移行後の構成

移行後は、次の構成とする。

ローカル環境
  ├── VSCode
  ├── Python
  ├── uv
  └── MkDocs
       |
       | git push
       v
GitHub
  ├── main
  │    └── 本番公開用
  │
  └── develop
       └── プレビュー用
       |
       v
Cloudflare Pages
  ├── 本番環境
  └── プレビュー環境

GitHub はソースコードの管理に使用し、Cloudflare Pages はビルドとサイト公開を担当する。

ローカルの開発環境は、これまでと同様に VSCode、Python、uv、MkDocs を使用する。

3. Cloudflare Pages の特徴

GitHub Pages と Cloudflare Pages を比較する。

項目 GitHub Pages Cloudflare Pages
静的サイト公開 ○ ○
GitHub連携 ○ ○
Git pushによる自動公開 ○ ○
プレビュー環境 △ ○
独自ドメイン ○ ○
HTTPS ○ ○
CDN ○ ○
アクセス制限 限定的 Cloudflare Access

Cloudflare Pages の主な特徴は次のとおり。

  • GitHub と連携した自動ビルド・デプロイ
  • ブランチごとのプレビュー環境
  • Pull Request ごとのプレビューURL
  • 独自ドメインの設定
  • Cloudflare Access によるアクセス制限

また、1つの Cloudflare アカウントで複数の Pages プロジェクトを管理できる。

例えば、MkDocs のプロジェクトごとに Pages プロジェクトを作成すれば、それぞれ独立して公開できる。

4. GitHub リポジトリとの連携

4.1 Cloudflare アカウント

Cloudflare にアクセスし、アカウントを作成する。

4.2 Pages プロジェクトの作成

Cloudflare の管理画面から、次の手順で進める。

  1. Workers & Pages を開く
  2. Create application を選択
  3. Pages に続行を選択
  4. GitHub リポジトリとの連携を選択
  5. GitHub アカウントを認証する
  6. 対象の MkDocs リポジトリを選択する

GitHub との連携時には、Cloudflare に対象リポジトリへのアクセスを許可する。

4.3 ビルド設定

Pages プロジェクトの作成時に、次のように設定する。

項目 設定値
Project name プロジェクト名
Production branch main
Framework preset None
Build command 後述
Build output directory site
Root directory リポジトリのルート

MkDocs のビルド結果は site ディレクトリに生成されるため、Build output directory には site を指定する。

GitHub リポジトリのルートに mkdocs.yml がある場合、Root directory は変更しない。

5. uv によるビルド環境の構築

Cloudflare Pages のビルド環境で uv を利用する。

5.1 Python のバージョン

今回の Cloudflare Pages のビルド環境では、.python-version を用意しなくても正常にビルドできた。

そのため、Python のバージョン指定ファイルは必須ではない。

特定のバージョンに固定したい場合は、Cloudflare Pages の環境変数 PYTHON_VERSION などを利用する。

5.2 uv による依存関係の管理

既存の pyproject.toml と uv.lock を利用する。

これらのファイルは、基本的に変更する必要はない。

特に uv.lock は GitHub リポジトリにコミットしておく。

5.3 ビルドコマンド

Cloudflare Pages の Build command に次のコマンドを指定する。

curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" && uv sync --frozen && uv run mkdocs build

各コマンドの役割は次のとおり。

コマンド 処理内容
curl ... install.sh uv のインストール
export PATH=... uv の実行パスを追加
uv sync --frozen uv.lock に従って依存関係を同期
uv run mkdocs build MkDocs によるサイト生成

--frozen を指定することで、ビルド時にロックファイルを更新せず、既存の依存関係を利用する。

5.4 環境変数

Cloudflare Pages の環境変数で、必要に応じて次の値を設定する。

変数 値
PYTHON_VERSION 3.13.7
SKIP_DEPENDENCY_INSTALL 1

Python のバージョン指定は必須ではない。今回の環境では .python-version がなくても正常に動作した。

SKIP_DEPENDENCY_INSTALL は Cloudflare 側の自動依存関係インストールを無効にし、uv によるインストールに統一するための設定である。

5.5 デプロイコマンドとプレビューコマンド

今回の Pages の Git 連携方式では、ビルドコマンドと出力ディレクトリを指定すればよい。

Deploy command と Preview command は使用しないため、空欄にする。

プレビュー環境のビルドは、ブランチ設定に従って Cloudflare Pages が自動的に実行する。

6. プレビュー環境の構築

Cloudflare Pages では、本番環境とは別にプレビュー環境を作成できる。

GitHub のブランチを利用することで、本番公開前のサイトを確認できる。

6.1 ブランチ構成

今回は、次の2つのブランチで運用する。

ブランチ 用途
main 本番公開
develop プレビュー

main への push で本番環境が更新され、develop への push でプレビュー環境が更新される。

6.2 ブランチの作成

ローカル環境で develop ブランチを作成する。

git switch -c develop
git push -u origin develop

これにより、GitHub に develop ブランチが作成される。

6.3 Cloudflare のブランチ設定

Cloudflare Pages の設定画面から、次の項目を確認する。

Settings → Builds & deployments → Branch control

項目 設定
Production branch main
Preview branches All non-Production branches

これにより、main 以外のブランチがプレビュー対象になる。

特定のブランチだけをプレビュー対象にしたい場合は、Custom branches を選択して対象を指定する。

6.4 プレビューURL

例えば、プロジェクト名が mkdocs-sample の場合、プレビュー環境には次のようなURLが割り当てられる。

https://develop.mkdocs-sample.pages.dev/

また、デプロイごとに固有のハッシュを含むURLも発行される。

https://xxxxxxxx.mkdocs-sample.pages.dev/

ブランチ名のエイリアスは、そのブランチの最新デプロイを指す。

そのため、develop に変更を push すると、同じブランチ用URLから最新の内容を確認できる。

Pull Request を作成した場合にも、専用のプレビューURLが発行される。

6.5 日常的な運用

普段は develop で記事の作成や修正を行い、プレビュー環境で表示を確認する。

問題がなければ main にマージする。

develop
   |
   | 記事の作成・修正
   v
プレビュー環境で確認
   |
   | 問題がなければマージ
   v
main
   |
   v
本番環境に公開

7. プレビュー環境のアクセス制限

Cloudflare Pages のプレビュー環境は、初期状態では公開されている。

つまり、URL を知っていれば誰でも閲覧できる。

公開前の記事や資料を確認する場合は、Cloudflare Access を利用してアクセスを制限できる。

7.1 Cloudflare Access の設定

Cloudflare Dashboard で次の操作を行う。

  1. Workers & Pages を開く
  2. 対象の Pages プロジェクトを選択
  3. Settings を開く
  4. General を開く
  5. Enable access policy を有効にする

これにより、プレビュー環境に Cloudflare Access が適用される。

7.2 アクセス制限の範囲

注意したいのは、Pages の Enable access policy が保護するのはプレビュー環境であるという点。

URL アクセス制限
develop.mkdocs-sample.pages.dev 保護対象
xxxxxxxx.mkdocs-sample.pages.dev 保護対象
mkdocs-sample.pages.dev 別途設定が必要

本番環境や独自ドメインも保護したい場合は、Cloudflare Access で別途ポリシーを設定する必要がある。

7.3 アクセスを許可するユーザー

Cloudflare Access では、メールアドレスなどを利用してアクセスを許可するユーザーを指定できる。

例えば、自分のメールアドレスだけを許可すれば、自分だけがプレビュー環境を閲覧できる。

8. GitHub Pages からの切り替え

Cloudflare Pages で正常に公開できたら、GitHub Pages から切り替える。

ただし、すぐに GitHub Pages を停止する必要はない。

次の順番で進める。

  1. Cloudflare Pages で初回デプロイ
  2. pages.dev のURLで表示を確認
  3. Markdown、画像、数式、検索機能などを確認
  4. GitHub に変更を push して自動デプロイを確認
  5. 問題がなければ GitHub Pages の公開を停止する

GitHub Pages で使用していた username.github.io は GitHub が提供するドメインであり、そのまま Cloudflare Pages に移すことはできない。

同じURLを維持したい場合は、独自ドメインを用意して Cloudflare に接続する必要がある。

9. 移行後の運用

移行後の日常的な作業は、これまでとほぼ同じである。

作業 コマンド
ローカルプレビュー uv run mkdocs serve --dirty
ローカルビルド uv run mkdocs build
依存関係の同期 uv sync
GitHubへの反映 git push
Cloudflareへの公開 自動デプロイ

これまで使用していた mkdocs gh-deploy は、通常の公開作業では使用しなくなる。

GitHub への push を契機に Cloudflare Pages が自動的にビルド・デプロイするためである。

10. まとめ

GitHub Pages から Cloudflare Pages に移行することで、GitHub をソースコード管理に使用しながら、Cloudflare にビルドと公開を任せる構成にできる。

また、ブランチを利用したプレビュー環境を用意すれば、本番公開前に記事やサイトの表示を確認できる。

今回の構成では、次のように役割を分担する。

サービス・ツール 役割
Emacs Markdown の編集
Python 実行環境
uv Python パッケージ管理
MkDocs 静的サイト生成
GitHub ソースコード管理
Cloudflare Pages ビルド・サイト公開
Cloudflare Access プレビュー環境のアクセス制限

これにより、複数の MkDocs サイトも、それぞれ独立した Cloudflare Pages プロジェクトとして管理できる。

参考