レビューアプリ

レビューアプリは、製品の変更を紹介する環境を提供するコラボレーションツールです。

note
Kubernetesクラスターがあれば、Auto DevOpsを使ってアプリケーションのこの機能を自動化できます。

レビューアプリ:

  • マージリクエスト用の動的環境をスピンアップすることで、機能ブランチで行われた変更の自動ライブプレビューを提供します。
  • ブランチをチェックアウトしてサンドボックス環境で変更を実行しなくても、デザイナーやプロダクトマネージャーが変更を確認できます。
  • GitLab DevOpsライフサイクルと完全にインテグレーションされています。
  • 好きな場所に変更をデプロイできます。

review apps workflow

前の例では

  • レビューアプリは、コミットがtopic branch にプッシュされるたびにビルドされます。
  • レビュアーは3つ目のレビューに合格する前に2つのレビューに失敗します。
  • レビューが通ると、topic branch がデフォルトブランチにマージされ、そこからステージングにデプロイされます。
  • ステージでの承認者の承認を経て、デフォルトブランチにマージされた変更が本番環境にデプロイされます。

レビューアプリの仕組み

レビューアプリは、ブランチと環境のマッピングです。レビューアプリへのアクセスは、ブランチに関連するマージリクエストのリンクとして利用できます。

以下は、環境を動的に設定したマージリクエストの例です。

review app in merge request

この例では、ブランチは

  • ビルドに成功しました。
  • アプリを表示]を選択して到達できる動的環境下でデプロイされました。

ワークフローにレビューアプリを追加したら、ブランチされたGitフローに従います。つまり

  1. ブランチをプッシュし、動的環境ジョブのscript 定義に基づいてランナーにレビューアプリをデプロイさせます。
  2. Runner が Web アプリケーションをビルドしてデプロイするのを待ちます。
  3. 変更をライブで見るには、ブランチに関連するマージリクエストのリンクを選択してください。

レビューアプリの設定

レビュアーアプリは動的環境上に構築されており、ブランチごとに動的に新しい環境を作成することができます。

レビューアプリの設定手順は次のとおりです:

  1. レビューアプリをホストし、デプロイするためのインフラストラクチャをセットアップします(以下の例を参照してください)。
  2. デプロイを実行するRunnerをインストールして設定します。
  3. .gitlab-ci.yml でジョブをセットアップします。このジョブは定義済みの CI/CD 変数 ${CI_COMMIT_REF_SLUG} を使って動的環境を作り、ブランチ上でのみ実行するように制限します。代わりに、プロジェクトのレビューアプリを有効にすることで、このジョブのYAMLテンプレートを取得できます。
  4. オプションで、レビューアプリを手動で停止するジョブを設定します。

レビューアプリを有効にするボタン

GitLab 12.8で導入されました

プロジェクトにレビューアプリを設定する際、.gitlab-ci.yml 上記のようにファイルに .gitlab-ci.yml新しいジョブを追加します。.gitlab-ci.yml これを簡単にするために、そしてKubernetesを使っているのであれば、レビューアプリを有効にする .gitlab-ci.yml.gitlab-ci.yml 選択すると、GitLabは .gitlab-ci.yml開始点として.gitlab-ci.yml コピー&ペーストできるテンプレートコードブロックを .gitlab-ci.yml表示します。

前提条件

  • プロジェクトには少なくとも開発者ロールが必要です。

レビュアーテンプレートを使用するには:

  1. 左側のサイドバーで、レビューアプリのジョブを作成したいプロジェクトを検索するか、「検索」を選択します。
  2. Build (ビルド)] > [Environments (環境)] を選択します。
  3. Enable review apps(レビューアプリを有効にする)を選択します。
  4. 提供されたコードスニペットをコピーし、.gitlab-ci.yml ファイルに貼り付けます:

    enable review apps modal

このテンプレートは必要に応じて編集することができます。

レビューアプリの自動停止

一定期間後にレビューアプリの環境が期限切れとなり、自動停止するように設定する方法をご覧ください。

レビューアプリの例

以下はレビューアプリの設定を示すサンプルプロジェクトです:

プロジェクト設定ファイル
NGINX.gitlab-ci.yml
OpenShift.gitlab-ci.yml
HashiCorp Nomad.gitlab-ci.yml
GitLab ドキュメントbuild-and-deploy.gitlab-ci.yml
https://about.gitlab.com/.gitlab-ci.yml
GitLab インサイト.gitlab-ci.yml

その他のレビューアプリの例

ルートマップ

Route Mapsを使用すると、ソースファイルからレビュアー用に定義された環境上の公開ページに直接移動することができます。

一度セットアップすれば、マージリクエストウィジェットのレビューアプリリンクから変更されたページに直接移動することができ、提案された修正をより簡単かつ迅速にプレビューすることができます。

Route Maps の設定では、Route Map を使ってリポジトリ内のファイルのパスとウェブサイト上のページのパスを GitLab に伝えます。設定すると、GitLab はView on …ボタンを表示し、マージリクエストから直接変更されたページに移動できるようになります。

ルートマップを設定するには、リポジトリ内部.gitlab/route-map.yml にファイルを追加します。このファイルには、(リポジトリ内の)source のパスと(ウェブサイト上の)public のパスをマップする YAML 配列がコンテナとして含まれています。

ルートマップの例

以下は、GitLabのウェブサイトを構築するために使われる静的サイトジェネレータ(SSG) 、GitLab.com上のプロジェクトからデプロイされたMiddlemanのルートマップの例です:

# Team data
- source: 'data/team.yml'  # data/team.yml
  public: 'team/'  # team/

# Blogposts
- source: /source\/posts\/([0-9]{4})-([0-9]{2})-([0-9]{2})-(.+?)\..*/  # source/posts/2017-01-30-around-the-world-in-6-releases.html.md.erb
  public: '\1/\2/\3/\4/'  # 2017/01/30/around-the-world-in-6-releases/

# HTML files
- source: /source\/(.+?\.html).*/  # source/index.html.haml
  public: '\1'  # index.html

# Other files
- source: /source\/(.*)/  # source/images/blogimages/around-the-world-in-6-releases-cover.png
  public: '\1'  # images/blogimages/around-the-world-in-6-releases-cover.png

マッピングはルート YAML 配列のエントリとして定義され、- プレフィックスで識別されます。エントリの中には2つのキーを持つハッシュマップがあります:

  • source
    • 完全一致のための' で始まり で終わる文字列です。
    • / で始まり、 で終わる正規表現:
      • 正規表現はソース・パス全体にマッチする必要があります -^ および$ アンカーは暗黙の了解です。
      • public パスで参照できる() で示されるキャプチャグループを含めることができます。
      • スラッシュ(/)は\/ としてエスケープできますが、その必要はありません。
      • ピリオド (.) は\. のようにエスケープしてください。
  • publicで始まり、' で終わる文字列。
    • source 正規表現内のキャプチャグループを、\1 から始まる出現順に参照するために、\N 表現を含めることができます。

ソース・パスの公開パスは、それにマッチする最初のsource 式を見つけ、対応するpublic パスを返します。\N 式は、必要に応じて() キャプチャ・グループの値に置き換えられます。

上記の例では、マッピングは定義順に評価されるという事実を利用して、source/index.html.haml/source\/(.*)/ ではなく/source\/(.+?\.html).*/ に一致するようにし、その結果、公開パスはindex.html.hamlではなくindex.html になります。

ルートマッピングを設定すると、次の場所で有効になります:

  • マージリクエストウィジェット内:
    • アプリを表示]ボタンをクリックすると、.gitlab-ci.yml ファイルに設定された環境 URL に移動します。
    • リストにはルートマップから最初にマッチした5つの項目が表示されますが、5つ以上ある場合はフィルタリングすることができます。

      View app file list in merge request widget

  • 比較またはコミットの diff で、ファイルの横にある表示({外部リンク}) を選択します。

  • blobファイルビューで、ファイルの横にある表示({external-link})を選択します。

ビジュアルレビュー(非推奨)

caution
この機能はGitLab 15.8で非推奨となり、17.0で削除される予定です。この変更はブレークチェンジです。

フラグ: セルフマネジメントのGitLabでは、デフォルトではこの機能は利用できません。利用可能にするには、管理者がanonymous_visual_review_feedbackという機能フラグを有効にします。

ビジュアルレビューでは、どのチーム(プロダクト、デザイン、品質など)のメンバーもレビューアプリのフォームからフィードバックコメントを提供できます。コメントは、レビューアプリのトリガーとなったマージリクエストに追加されます。

ビジュアルレビューの使用方法

レビューアプリにビジュアルレビューが設定されると、各ページの右側にビジュアルレビューのフィードバックフォームがオーバーレイ表示されます。

Visual review feedback form

フィードバックフォームを使用して、マージリクエストにコメントを入力します:

  1. ページの右側で、レビュータブを選択します。
  2. ビジュアルレビューにコメントを付けます。マージリクエストコメントでも利用可能なすべてのマークダウン注釈を利用することができます。
  3. 個人情報を入力してください:
  4. フィードバックを送信」を選択します。

ビジュアルレビューのアクションについては、ビジュアルレビューのウォークスルーをご覧ください。

ビジュアルレビュー用のレビューアプリの設定

フィードバックフォームはレビューアプリのページに追加するスクリプトを通して提供されます。スクリプトはアプリケーションの<head> に追加する必要があり、プロジェクトやマージリクエスト固有の値で構成されます。ここでは、GitLab.com のプロジェクトでコードをホストしているプロジェクトについて説明します:

<script
  data-project-id='11790219'
  data-merge-request-id='1'
  data-mr-url='https://gitlab.com'
  data-project-path='sarah/review-app-tester'
  data-require-auth='true'
  id='review-app-toolbar-script'
  src='https://gitlab.com/assets/webpack/visual_review_toolbar.js'>
</script>

理想的には、各レビューアプリが作成されるときに、CI/CD 変数を使って実行時にこれらの値を置き換えるべきです:

  • data-project-id はプロジェクトIDで、CI_PROJECT_ID 変数で見つけることができます。
  • data-merge-request-id はマージリクエストIDで、CI_MERGE_REQUEST_IID 変数 CI_MERGE_REQUEST_IID rules:if: $CI_PIPELINE_SOURCE == "merge_request_event が使用され、マージリクエストが作成された場合のみ利用可能です。
  • data-mr-url は GitLab インスタンスの URL で、すべてのレビューアプリで同じです。
  • data-project-path はプロジェクトのパスで、CI_PROJECT_PATH で見つけることができます。
  • data-require-auth は公開プロジェクトでは任意ですが、非公開プロジェクトや内部プロジェクトでは必須です。これがtrueに設定されている場合、ユーザーは名前とメールアドレスの代わりに個人アクセストークンを入力する必要があります。
  • id が常にreview-app-toolbar-script の場合は変更する必要はありません。
  • src はレビューツールバースクリプトのソースで、それぞれのGitLabインスタンスに存在し、すべてのレビューアプリで同じです。

例えば、Ruby アプリケーションで GitLab.com というプロジェクトにコードをホストしている場合、このスクリプトが必要になります:

<script
  data-project-id="ENV['CI_PROJECT_ID']"
  data-merge-request-id="ENV['CI_MERGE_REQUEST_IID']"
  data-mr-url='https://gitlab.com'
  data-project-path="ENV['CI_PROJECT_PATH']"
  id='review-app-toolbar-script'
  src='https://gitlab.com/assets/webpack/visual_review_toolbar.js'>
</script>

そして、アプリが GitLab CI/CD でデプロイされると、これらの変数は実際の値に置き換えられます。

マージリクエスト ID の決定

ビジュアルレビューツールは、レビューアプリにビジュアルレビューツールを追加するために使用したscript HTML タグに含まれるdata-merge-request-id data 属性からマージリクエスト ID を取得します。

ビジュアルレビューアプリにリンクするマージリクエストの ID を決定したら、その ID を指定します:

  • アプリの data 属性data-merge-request-id を介してスクリプトタグにハードコーディングします。
  • アプリのビルド中にdata-merge-request-id の値を動的に追加します。
  • アプリのビジュアルレビューフォームから手動で提供。

script に ID がない場合、ビジュアルレビューツールはフィードバックを提供する前にマージリクエスト ID の入力を促します。

ビジュアルレビューの認証

GitLab 12.10で導入されました

非公開プロジェクトや内部プロジェクトでビジュアルレビューを有効にするには、data-require-auth 変数trueに設定します。有効にすると、ユーザーはフィードバックを投稿する前にapi スコープで個人アクセストークンを入力する必要があります。

これと同じ方法で、公開プロジェクトでも認証が必要になります。