ドキュメントサイトの公開・更新

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認証は別の設定です。

通常の更新

  1. MarkdownやMkDocs設定を変更し、ローカルでmkdocs build --strictを実行します。
  2. 変更をmainへマージします。
  3. docs:buildが成功すると、docs:deployがCloudflare Pagesの本番へアップロードします。
  4. 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で本番・プレビュー・独自ドメインをそれぞれ保護しているか

公式資料