レビューアプリ

  • GitLab 8.12で導入され、GitLab 8.13と8.14でさらに追加されました。
  • Herokuのレビューアプリに触発され、それ自体がFourchetteに触発されました。

レビューアプリは、製品の変更を発表する環境を提供する苦労を軽減するコラボレーションツールです。

導入

レビューアプリ:

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

Review Apps Workflow

上記の例では

  • レビューアプリは、コミットがtopic branchにプッシュされるたびにビルドされます。
  • レビュアーは3回目の審査に合格する前に2回の審査に落ちます。
  • レビュアーが通過すると、topic branchmaster にマージされ、ステージングにデプロイされます。
  • ステージングで承認された後、master にマージされた変更が本番環境にデプロイされます。

レビューアプリの仕組み

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

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

Review App in merge request

この例では、ブランチがありました:

  • 建設に成功
  • アプリの表示]ボタンをクリックすると表示される動的環境下にデプロイされます。

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

  1. ブランチをプッシュし、ダイナミック環境ジョブのscript 定義に基づいてレビュアーにレビューアプリをデプロイさせます。
  2. RunnerがWebアプリケーションをビルドし、デプロイするのを待ちます。
  3. ブランチに関連するマージリクエストにあるリンクをクリックすると、変更が反映されます。

レビューアプリの設定

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

レビューアプリの設定方法は以下の通りです:

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

レビューアプリの有効化ボタン

GitLab 12.8で導入されました

プロジェクトにレビューアプリを設定するときは、.gitlab-ci.yml前述のように、 .gitlab-ci.yml新しいジョブを.gitlab-ci.yml, .gitlab-ci.ymlに追加する必要があります.gitlab-ci.yml。 これを簡単にするために、また .gitlab-ci.ymlKubernetes.gitlab-ci.ymlを使っている場合は、レビューアプリを有効にするボタンをクリックすると、 .gitlab-ci.ymlGitLab.gitlab-ci.ymlがテンプレートコードブロックを表示してくれるので、それをコピーして貼り付ける .gitlab-ci.ymlことができます。 そのためには、次のようにします:

  1. レビューアプリのジョブを作成したいプロジェクトに移動します。
  2. 左のナビから、オペレーション>環境と進みます。
  3. レビューアプリを有効にする]ボタンをクリックします。 このボタンは、そのプロジェクトに開発者以上の権限がある場合に使用できます。
  4. 提供されたコード・スニペットをコピーし、.gitlab-ci.yml ファイルに貼り付けてください:

    Enable Review Apps modal

  5. このテンプレートは、あなたのニーズに合わせて自由に調整してください。

レビュー アプリ 自動停止

一定期間経過後に有効期限が切れて自動停止するようにレビューアプリ環境を設定する方法をご覧ください。

レビューアプリの例

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

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

ルートマップ

GitLab 8.17で導入され、GitLab 11.5ではマージリクエストウィジェットでファイルリンクが利用できるようになりました。

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

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

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

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

ルートマップの例

以下は、GitLab.com上のプロジェクトからデプロイされた、GitLabのウェブサイトを構築するために使われる静的サイトジェネレーター(SSG) 、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になるようにしています。

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

  • マージリクエストウィジェットでは、次のようになります:
    • View appボタンを押すと、.gitlab-ci.ymlで設定した環境 URL に移動します。
    • ドロップダウンには、ルートマップから最初にマッチした5つの項目が表示されますが、5つ以上ある場合は絞り込むことができます。

      View app file list in merge request widget

  • マージリクエスト、比較、コミットの差分。

    "View on env" button in merge request diff

  • ブロブファイルビューで

    "View on env" button in file view

ビジュアルレビュー

GitLab Starter 12.0で導入されました

ビジュアルレビューでは、レビューアプリにフィードバックフォームを提供し、レビュアーがアプリから直接、レビューアプリを作成したマージリクエストにコメントを投稿することができます。

ビジュアルレビューの設定

anonymous_visual_review_feedback featureフラグが有効になっていることを確認してください。管理者はRailsコンソールで次のように有効にできます:

Feature.enable(:anonymous_visual_review_feedback)

フィードバックフォームは、レビューアプリのページに追加したスクリプトを通して提供されます。 プロジェクトの開発者権限を持っている場合、マージリクエストのパイプラインセクションにあるレビューボタンをクリックすることでアクセスできます。ルートマップがプロジェクトに設定されている場合、フォームモーダルには変更されたページのドロップダウンも表示されます。

review button

提供されるスクリプトはアプリケーションの<head> に追加され、いくつかのプロジェクトとマージリクエスト固有の値で構成されます。 これは以下のようになります:

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

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

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

例えば、Rubyアプリケーションでは次のようなスクリプトが必要です:

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

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

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

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

ビジュアルレビューアプリにリンクするマージリクエストのIDを決定した後、以下のいずれかの方法でIDを提供できます。

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

非公開プロジェクトや内部プロジェクトでのビジュアルレビュー

GitLab 12.10 で導入されました

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

ビジュアルレビューの活用

レビューアプリでビジュアルレビューを有効にすると、アプリのページ右下にビジュアルレビューのフィードバックフォームがオーバーレイ表示されます。

Visual review feedback form

フィードバックフォームを使用するには

  1. マージリクエストコメントでも利用可能なすべてのマークダウン注釈を利用することができます。
  2. data-require-authtrueの場合は、個人アクセストークンを入力する必要があります。それ以外の場合は、名前と、オプションで電子メールを入力する必要があります。
  3. 最後に、「フィードバックを送信」をクリックします。

ビジュアルレビューボックスでコメントを作成し送信すると、それぞれのマージリクエストに自動的に表示されます。

制限事項

レビューアプリの制限は環境の制限と同じです。