ドキュメントサイトの公開・更新¶
docs/ のMarkdownをMkDocsでHTMLへ変換し、オンプレミスのGitLab RunnerからCloudflare Pagesへアップロードします。本体サイトのNGINXへの配置とは別に実行します。
CloudflareとGitLabの初回設定¶
CloudflareのWorkers & PagesからPagesのDirect Uploadプロジェクトを作成します。管理画面では「Drag and drop your files」から仮のindex.htmlをアップロードして作成できます。本番ブランチはmainとし、Git連携は設定しません。ビルドはRunnerで行うため、Cloudflare側にビルドコマンドは不要です。
CI用APIトークンにはAccount → Cloudflare Pages → Editを付与し、対象アカウントに限定します。GitLabのSettings → CI/CD → Variablesで以下を登録します。
| キー | 内容 |
|---|---|
CLOUDFLARE_API_TOKEN |
Pagesへのアップロード用APIトークン |
CLOUDFLARE_ACCOUNT_ID |
プロジェクトを作成したアカウントのID。Zone IDとは異なる |
CLOUDFLARE_PAGES_PROJECT_NAME |
Pagesのプロジェクト名。URL全体ではなく名前だけ |
いずれもTypeはVariable、環境スコープはdocumentationまたは*とし、変数展開を無効にします。トークンはMasked(対応していればMasked and hidden)、Protectedを有効にします。mainも保護ブランチに設定してください。環境スコープがproductionだけの変数は、文書用デプロイジョブには渡りません。
RunnerからPythonパッケージの取得先、npmレジストリ、Cloudflare APIへのHTTPS接続が必要です。本体の公開用SSH鍵は文書の配置には使いません。
閲覧制限¶
運用文書を社内限定にする場合は、文書の初回アップロード前にCloudflare Zero Trustの初期登録を済ませ、Cloudflare Accessで許可する閲覧者を設定します。
Pagesの「Enable access policy」で作成されるポリシーはプレビュー用です。Accessアプリケーションのホスト名からワイルドカードを取り除き、本番の<project>.pages.devを保護します。その後、Pages側で再度「Enable access policy」を有効にし、*.<project>.pages.devのプレビュー用ポリシーも作成します。独自ドメインを追加する場合は、そのホスト名にもAccessアプリケーションが必要です。
シークレットウィンドウで、本番URLとデプロイ固有のプレビューURLの両方が認証を要求することを確認します。Pagesへのアップロード用APIトークンと、閲覧者のAccess認証は別の設定です。
通常の更新¶
- MarkdownやMkDocs設定を変更し、ローカルで
mkdocs build --strictを実行します。 - 変更を
mainへマージします。 docs:buildが成功すると、docs:deployがCloudflare Pagesの本番へアップロードします。- Pagesのデプロイ結果と、公開されたページの表示・検索・リンクを確認します。
対象は、保護されたmainへのpushで、リポジトリ直下のREADME.mdまたはdocs/配下に変更がある場合です。マージもmainへのpushとして扱います。マージ時だけ実行する運用では、GitLabのmainの保護設定で直接pushを禁止してください。タグは不要です。作業ブランチ、MR、タグ、スケジュール、Run pipelineからは文書用ジョブを実行しません。
mkdocs.yml、requirements-docs.txt、scripts/mkdocs-hooks.py、.gitlab-ci.ymlだけの変更では、文書のデプロイは実行しません。設定変更を反映したい場合は、README.mdまたはdocs/の説明も同じマージで更新してください。
docs:buildはリンク先や見出しの参照を検査し、警告がある場合も失敗させます。生成したsite/を7日間成果物として保存し、デプロイジョブへ渡します。文書用デプロイはdocumentation環境・リソースグループで実行します。GitLabの「Prevent outdated deployment jobs」も有効にし、古いパイプラインによる上書きを防いでください。
CIで生成するソースコードへのリンクは、CI_PROJECT_URLとCI_COMMIT_SHAを使い、ビルド対象コミットのGitLab画面へ向けます。ソースコード自体は文書サイトへコピーしません。GitLabへのアクセスには、社内ネットワークへの接続やGitLabへのログインが別途必要です。
ローカルでの確認¶
WindowsのPowerShellで、リポジトリのルートから実行します。
python -m venv .venv-docs
.venv-docs/Scripts/python -m pip install -r requirements-docs.txt
.venv-docs/Scripts/python -m mkdocs build --strict
.venv-docs/Scripts/python -m mkdocs serve
開発サーバーはhttp://127.0.0.1:8000/です。docs/README.mdがトップページになり、図のHTML・画像も公開対象に含まれます。ローカルではGitLabの環境変数がないため、リポジトリ内のソースへのリンクはファイルパスの文字列で表示します。
失敗した場合¶
| 症状 | 確認箇所 |
|---|---|
| パイプラインが作られない | mainが保護されているか、変更ファイルが対象に含まれるか |
| ビルドでリンク警告が出る | 相対パス、ファイル名の大文字小文字、見出しのアンカー |
CLOUDFLARE_* is required |
変数名、Type、Protected設定、環境スコープ |
| Cloudflareの認証・権限エラー | APIトークンの有効性とPages Edit権限、Account ID |
| 本番ページが更新されない | プロジェクト名と本番ブランチがmainか、デプロイがProduction扱いか |
| 認証なしで閲覧できる | Accessで本番・プレビュー・独自ドメインをそれぞれ保護しているか |