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 の管理画面から、次の手順で進める。
- Workers & Pages を開く
- Create application を選択
- Pages に続行を選択
- GitHub リポジトリとの連携を選択
- GitHub アカウントを認証する
- 対象の 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 で次の操作を行う。
- Workers & Pages を開く
- 対象の Pages プロジェクトを選択
- Settings を開く
- General を開く
- 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 を停止する必要はない。
次の順番で進める。
- Cloudflare Pages で初回デプロイ
pages.devのURLで表示を確認- Markdown、画像、数式、検索機能などを確認
- GitHub に変更を push して自動デプロイを確認
- 問題がなければ 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 プロジェクトとして管理できる。