マージリクエストの画面からドキュメントのプレビューを開けるようにする（!29 修正）

Kanato Konorequested to merge
chikasuiro/frontistr_documents:feature/expose-docs-preview into main

課題

  • CIが生成した site はアーティファクトとして保持されるが、GitLab Pages への公開は main とタグに限られている
  • MRの段階で変更後のページを確認するには、パイプライン → ジョブ → アーティファクトのブラウズと辿るか、ローカルにクローンして mkdocs serve する必要がある
  • このためレビュワーが表示を確認しづらく、レビューの負担になっている

先行する !29 (closed)（mkdocs ジョブへの expose_as の追加）では、次の2点が課題として残っている。

  • MR画面にリンクが表示されない: artifacts:paths が site（末尾スラッシュ無し）のままであるため、GitLabの仕様上ディレクトリが露出されない。実際に !29 (closed) のMR画面用エンドポイントは空の結果を返しており、「docs preview」リンクは出ていない
  • リンク先が描画済みページではない: expose_as のリンク先はアーティファクトブラウザ（ファイル一覧）であり、そこから index.html を選んでも中間ページを1つ挟むため、変更後のページに直接到達できない

変更内容

mkdocs ジョブに以下を追加する。

  environment:
    name: docs-preview/$CI_COMMIT_REF_SLUG
    url: "https://$CI_PROJECT_ROOT_NAMESPACE.$CI_PAGES_DOMAIN/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/site/index.html"
  artifacts:
    paths:
      - site/
    expose_as: 'docs preview'
  • artifacts:paths の site に末尾スラッシュを付ける（課題の1点目に対応）。これによりMR画面に「docs preview」リンクが表示される
  • expose_as は !29 (closed) と同じくリンク名として用いる。リンク先はアーティファクトブラウザであり、特定のファイルを直接見たい場合に使える
  • environment のURLをアーティファクト配信ドメイン上の index.html に向ける（課題の2点目に対応）。MR画面のボタンから1クリックで描画済みのページを開ける

追加するジョブは無く、パイプラインの実行時間は変わらない。

動作確認

fork（chikasuiro/frontistr_documents）で実際にパイプラインを流して確認した。

  • MR画面に「docs preview」リンクと環境リンクの両方が表示される
  • 環境リンクはリダイレクトなしで HTTP 200・text/html を返し、CSS・サイドナビ・内部リンクが機能する。変更したページの内容が反映されることも確認した
  • fork由来のクロスプロジェクトMR（本MRと同じ構図）でも同様に表示される。Pages を一度もデプロイしていないforkでもプレビューは機能するため、投稿者側の準備は不要
  • 一意ドメインが無効な本リポジトリでも同じURL形式で配信されることを、本リポジトリのアーティファクトに対して確認した
  • artifacts の収集ファイル数は変更前後で同一（781件）であり、pages-main / pages-tag が受け取る内容は変わらない
  • style-check への影響は無い

補足

  • environment はブランチごとに作られ、そのブランチがマージまたは削除された時点で自動停止する。auto_stop_in は設定していない（期限を設けると、レビューが滞留したMRでプレビューが先に消えてしまうため）。プレビューの実質的な寿命はアーティファクトの失効（既定30日）で決まる
  • fork由来MRではパイプラインがfork側で実行されるため、環境は投稿者のfork内に作られる。本リポジトリの環境一覧が増えることはない
  • URLの組み立てはルート名前空間直下のプロジェクトであることを前提としている。サブグループ配下へ移動する場合は見直しが必要
  • Pages parallel deployments（pages: path_prefix でMRごとに実URLのプレビューを公開する方式）も検証したが、無料プランの名前空間では「Namespace reached its allowed limit of 0 extra deployments」で失敗する。fork由来MRは投稿者の名前空間で実行されるため投稿者のプランに依存してしまうこと、あわせてMRパイプラインの有効化と workflow:rules の追加が必要になることから、採用していない

Merge request reports