レビューアプリ
- GitLab 8.12で導入され、GitLab 8.13と8.14でさらに追加されました。
- Herokuのレビューアプリに触発され、それ自体がFourchetteに触発されました。
レビューアプリは、製品の変更を発表する環境を提供する苦労を軽減するコラボレーションツールです。
導入
レビューアプリ:
- マージリクエスト用に動的環境をスピンアップすることで、機能ブランチで行われた変更の自動ライブプレビューを提供します。
- ブランチをチェックアウトしてサンドボックス環境で変更を実行しなくても、デザイナーやプロダクトマネージャーが変更を確認できるようにします。
- GitLab DevOpsライフサイクルと完全にインテグレーションされています。
- 変更した内容を好きな場所にデプロイできます。
上記の例では
- レビューアプリは、コミットが
topic branch
にプッシュされるたびにビルドされます。 - レビュアーは3回目の審査に合格する前に2回の審査に落ちます。
- レビュアーが通過すると、
topic branch
はmaster
にマージされ、ステージングにデプロイされます。 - ステージングで承認された後、
master
にマージされた変更が本番環境にデプロイされます。
レビューアプリの仕組み
レビューアプリは、ブランチと環境のマッピングです。 レビューアプリへのアクセスは、ブランチに関連するマージリクエストのリンクとして利用できます。
以下は環境を動的に設定したマージリクエストの例です。
この例では、ブランチがありました:
- 建設に成功
- アプリの表示]ボタンをクリックすると表示される動的環境下にデプロイされます。
レビューアプリをワークフローに追加したら、ブランチ化されたGitフローに従います。 すなわち
- ブランチをプッシュし、ダイナミック環境ジョブの
script
定義に基づいてレビュアーにレビューアプリをデプロイさせます。 - RunnerがWebアプリケーションをビルドし、デプロイするのを待ちます。
- ブランチに関連するマージリクエストにあるリンクをクリックすると、変更が反映されます。
レビューアプリの設定
レビューアプリはダイナミック環境上に構築されており、ブランチごとに新しい環境を動的に作成することができます。
レビューアプリの設定方法は以下の通りです:
- レビューアプリをホストしてデプロイするためのインフラストラクチャをセットアップします(以下の例を確認してください)。
- デプロイを行うRunnerをインストールし、設定します。
-
.gitlab-ci.yml
で、定義済みの CI 環境変数${CI_COMMIT_REF_NAME}
を使って動的環境を作成し、ブランチ上でのみ実行するように制限するジョブをセットアップします。 あるいは、プロジェクトのレビュアーアプリを有効にすることで、このジョブの YML テンプレートを取得できます。 - オプションで、レビューアプリを手動で停止するジョブを設定します。
レビューアプリの有効化ボタン
GitLab 12.8で導入されました。
プロジェクトにレビューアプリを設定するときは、.gitlab-ci.yml
前述のように、 .gitlab-ci.yml
新しいジョブを.gitlab-ci.yml
, .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
ファイルに貼り付けてください: - このテンプレートは、あなたのニーズに合わせて自由に調整してください。
レビュー アプリ 自動停止
一定期間経過後に有効期限が切れて自動停止するようにレビューアプリ環境を設定する方法をご覧ください。
レビューアプリの例
以下はレビューアプリの設定を示すサンプルプロジェクトです:
レビューアプリの他の例:
- GitLabによるクラウドネイティブ開発。
- Android用レビューアプリ。
ルートマップ
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
になるようにしています。
ルートマッピングを設定すると、以下の場所で有効になります:
- マージリクエストウィジェットでは、次のようになります:
-
マージリクエスト、比較、コミットの差分。
-
ブロブファイルビューで
ビジュアルレビュー
GitLab Starter 12.0で導入されました。
ビジュアルレビューでは、レビューアプリにフィードバックフォームを提供し、レビュアーがアプリから直接、レビューアプリを作成したマージリクエストにコメントを投稿することができます。
ビジュアルレビューの設定
anonymous_visual_review_feedback
featureフラグが有効になっていることを確認してください。管理者はRailsコンソールで次のように有効にできます:
Feature.enable(:anonymous_visual_review_feedback)
フィードバックフォームは、レビューアプリのページに追加したスクリプトを通して提供されます。 プロジェクトの開発者権限を持っている場合、マージリクエストのパイプラインセクションにあるレビューボタンをクリックすることでアクセスできます。ルートマップがプロジェクトに設定されている場合、フォームモーダルには変更されたページのドロップダウンも表示されます。
提供されるスクリプトはアプリケーションの<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_IID
。CI_MERGE_REQUEST_IID
only: [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-id
data 属性からマージリクエスト ID を取得します。
ビジュアルレビューアプリにリンクするマージリクエストのIDを決定した後、以下のいずれかの方法でIDを提供できます。
- アプリのdata属性
data-merge-request-id
、scriptタグにハードコーディングします。 - アプリのビルド中に
data-merge-request-id
の値を動的に追加します。 - アプリのビジュアルレビューフォームから手動で提供します。
非公開プロジェクトや内部プロジェクトでのビジュアルレビュー
GitLab 12.10 で導入されました。
非公開プロジェクトや内部プロジェクトのビジュアルレビューを有効にするには、data-require-auth
変数 をtrue
に設定します。 有効にすると、ユーザーはフィードバックを提出する前に、api
スコープで個人アクセストークンを入力する必要があります。
ビジュアルレビューの活用
レビューアプリでビジュアルレビューを有効にすると、アプリのページ右下にビジュアルレビューのフィードバックフォームがオーバーレイ表示されます。
フィードバックフォームを使用するには
- マージリクエストコメントでも利用可能なすべてのマークダウン注釈を利用することができます。
-
data-require-auth
がtrue
の場合は、個人アクセストークンを入力する必要があります。それ以外の場合は、名前と、オプションで電子メールを入力する必要があります。 - 最後に、「フィードバックを送信」をクリックします。
ビジュアルレビューボックスでコメントを作成し送信すると、それぞれのマージリクエストに自動的に表示されます。
制限事項
レビューアプリの制限は環境の制限と同じです。