レビューアプリ

レビューアプリは、各ブランチや各マージリクエストに対して自動的に作成される一時的なテスト環境です。ローカル開発環境をセットアップしなくても、変更をプレビューしたり検証したりできます。

動的環境上に構築されたレビューアプリは、ブランチまたはマージリクエストごとに一意の環境を提供します。

これらの環境は、以下のように開発ワークフローの効率化に役立ちます:

• 変更をテストするためのローカルセットアップが不要になる。
• すべてのチームメンバーに一貫した環境を提供する。
• 関係者がURLを使用して変更をプレビューできる。
• 変更が本番環境に到達する前に、より迅速なフィードバックサイクルを促進する。

レビューアプリのワークフロー

レビューアプリのワークフローは、次のようなものになります:

%%{init: { "fontFamily": "GitLab Sans" }}%%
flowchart TD
    accTitle: Review app workflow
    accDescr: Diagram showing how review apps fit into the GitLab development workflow.

    subgraph Development["Development"]
        TopicBranch["Create topic branch"]
        Commit["Make code changes"]
        CreateMR["Create merge request"]
    end

    subgraph ReviewAppCycle["Review app cycle"]
        direction LR
        Pipeline["CI/CD pipeline runs"]
        ReviewApp["Review app deployed"]
        Testing["Review and testing"]
        Feedback["Feedback provided"]
        NewCommits["Address feedback
        with new commits"]
    end

    subgraph Deployment["Deployment"]
        Approval["Merge request approved"]
        Merge["Merged to default branch"]
        Production["Deployed to production"]
    end

    TopicBranch --> Commit
    Commit --> CreateMR
    CreateMR --> Pipeline

    Pipeline --> ReviewApp
    ReviewApp --> Testing
    Testing --> Feedback
    Feedback --> NewCommits
    NewCommits --> Pipeline

    Testing --> Approval
    Approval --> Merge
    Merge --> Production

    classDef devNode fill:#e1e1e1,stroke:#666,stroke-width:1px
    classDef reviewNode fill:#fff0dd,stroke:#f90,stroke-width:1px
    classDef finalNode fill:#d5f5ff,stroke:#0095cd,stroke-width:1px

    class TopicBranch,Commit,CreateMR devNode
    class Pipeline,ReviewApp,Testing,Feedback,NewCommits reviewNode
    class Approval,Merge,Production finalNode

レビューアプリを設定する

各ブランチまたはマージリクエストについて、アプリケーションのプレビュー環境を提供する場合、レビューアプリを設定します。

前提要件:

• プロジェクトのデベロッパーロール以上が必要です。
• プロジェクトでCI/CDパイプラインを利用できる必要があります。
• レビューアプリをホスティングおよびデプロイするためのインフラストラクチャをセットアップする必要があります。

プロジェクトでレビューアプリを設定するには、次のようにします:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにした場合、このフィールドは上部のバーにあります。

2. ビルド > パイプラインエディタを選択します。

3. .gitlab-ci.ymlファイルに、動的環境を作成するジョブを追加します。各環境を区別するために、定義済みCI/CD変数を使用できます。たとえば、CI_COMMIT_REF_SLUG定義済み変数を使用します:

   review_app:
     stage: deploy
     script:
       - echo "Deploy to review app environment"
       # Add your deployment commands here
     environment:
       name: review/$CI_COMMIT_REF_SLUG
       url: https://$CI_COMMIT_REF_SLUG.example.com
     rules:
       - if: $CI_COMMIT_BRANCH && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH

4. （オプション）ジョブにwhen: manualを追加して、レビューアプリを手動でのみデプロイできるようにします。

5. （オプション）不要になった際にレビューアプリを停止するジョブを追加します。

6. コミットメッセージを入力し、変更をコミットするを選択します。

レビューアプリテンプレートを使用する

GitLabには、マージリクエストパイプライン用にデフォルトで設定された組み込みテンプレートが用意されています。

このテンプレートを使用およびカスタマイズするには、次のようにします:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトを見つけます。新しいナビゲーションをオンにした場合、このフィールドは上部のバーにあります。

2. 操作 > 環境を選択します。

3. レビューアプリを有効にするを選択します。

4. 表示されるレビューアプリを有効にするダイアログから、YAMLテンプレートをコピーします:

   deploy_review:
     stage: deploy
     script:
       - echo "Add script here that deploys the code to your infrastructure"
     environment:
       name: review/$CI_COMMIT_REF_NAME
       url: https://$CI_ENVIRONMENT_SLUG.example.com
     rules:
       - if: $CI_PIPELINE_SOURCE == "merge_request_event"

5. ビルド > パイプラインエディタを選択します。

6. テンプレートを.gitlab-ci.ymlファイルに貼り付けます。

7. デプロイのニーズに基づいてテンプレートをカスタマイズします:

   • 実際のインフラストラクチャで動作するよう、デプロイスクリプトと環境URLに変更を加えます。
   • マージリクエストがなくてもブランチに対するレビューアプリをトリガーする必要がある場合は、rulesセクションを調整します。

   たとえば、Herokuへのデプロイの場合、次のようになります:

   deploy_review:
     stage: deploy
     image: ruby:latest
     script:
       - apt-get update -qy
       - apt-get install -y ruby-dev
       - gem install dpl
       - dpl --provider=heroku --app=$HEROKU_APP_NAME --api-key=$HEROKU_API_KEY
     environment:
       name: review/$CI_COMMIT_REF_NAME
       url: https://$HEROKU_APP_NAME.herokuapp.com
       on_stop: stop_review_app
     rules:
       - if: $CI_PIPELINE_SOURCE == "merge_request_event"

   この設定により、マージリクエストのパイプラインが実行されるたびにHerokuに自動デプロイされるようになります。プロセスの処理にはRubyのdplデプロイツールを使用しており、指定されたURLからアクセスできる動的レビュー環境を作成します。

8. コミットメッセージを入力し、変更をコミットするを選択します。

レビューアプリを停止する

リソースを節約するため、レビューアプリを手動または自動で停止するように設定できます。

レビューアプリ環境の停止の詳細については、環境を停止するを参照してください。

マージ時にレビューアプリを自動停止する

関連するマージリクエストがマージされるかブランチが削除された時点で、レビューアプリが自動的に停止するよう設定するには、次のようにします:

1. on_stopキーワードをデプロイメントジョブに追加します。
2. environment:action: stopを指定した停止ジョブを作成します。
3. （オプション）レビューアプリをいつでも手動で停止できるようにするには、停止ジョブにwhen: manualを追加します。

次に例を示します:

# In your .gitlab-ci.yml file
deploy_review:
  # Other configuration...
  environment:
    name: review/${CI_COMMIT_REF_NAME}
    url: https://${CI_ENVIRONMENT_SLUG}.example.com
    on_stop: stop_review_app  # References the stop_review_app job

stop_review_app:
  stage: deploy
  script:
    - echo "Stop review app"
    # Add your cleanup commands here
  environment:
    name: review/${CI_COMMIT_REF_NAME}
    action: stop
  when: manual  # Makes this job manually triggerable
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

時間ベースの自動停止

一定時間の経過後にレビューアプリが自動的に停止するよう設定するには、デプロイメントジョブにauto_stop_inキーワードを追加します:

# In your .gitlab-ci.yml file
review_app:
  script: deploy-review-app
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    auto_stop_in: 1 week  # Stops after one week of inactivity
  rules:
    - if: $CI_MERGE_REQUEST_ID

レビューアプリを表示する

レビューアプリをデプロイしてアクセスするには、次のようにします:

1. マージリクエストに移動します。
2. （オプション）レビューアプリジョブが手動の場合は、実行（ ）を選択してデプロイをトリガーします。
3. パイプラインが完了したら、アプリを表示を選択して、ブラウザーでレビューアプリを開きます。

実装例

以下のプロジェクトは、さまざまなレビューアプリの実装を示しています:

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

• Cloud Native Development with GitLab（GitLabを使用したクラウドネイティブ開発）。
• Android向けのレビューアプリ。

ルートマップ

ルートマップを使用すると、ソースファイルからレビューアプリ環境内の対応する公開ページに直接移動できます。この機能により、マージリクエスト内の特定の変更をより簡単にプレビューできます。

ルートマップを設定すると、コンテキストリンクが追加され、マッピングパターンに一致するファイルをレビューアプリ内で表示できるようになります。これらのリンクは以下に表示されます:

• マージリクエストウィジェット。
• コミットとファイルビュー。

ルートマップを設定する

ルートマップを設定するには、次のようにします:

1. リポジトリ内で.gitlab/route-map.ymlファイルを作成します。
2. ソースパス（リポジトリ内）と公開パス（レビューアプリのインフラストラクチャまたはウェブサイト上）のマッピングを定義します。

ルートマップはYAML配列で、その各エントリはsourceパスをpublicパスにマッピングします。

ルートマップ内の各マッピングの形式は次のとおりです:

- source: 'path/to/source/file'  # Source file in repository
  public: 'path/to/public/page'  # Public page on the website

次の2種類のマッピングを使用できます:

• 完全一致: 一重引用符で囲んだ文字列リテラル
• パターン一致: スラッシュで囲んだ正規表現

正規表現を使用したパターンマッチングの場合:

• 正規表現は、ソースパス全体と一致する必要があります（^と$のアンカーが暗黙的に先頭と末尾に付与されます）。
• ()のキャプチャグループを使用でき、publicパスで参照できます。
• キャプチャグループを参照するには、出現順に\N式（\1、\2など）を使用します。
• スラッシュ（/）は\/、ピリオド（.）は\.としてエスケープします。

GitLabは、定義された順にマッピングを評価します。最初に一致したsource式によってpublicパスが決定されます。

ルートマップの例

次の例は、GitLabウェブサイトで使用される静的サイトジェネレーターである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

この例では:

• マッピングが順番に評価されます。
• 3番目のマッピングにより、source/index.html.hamlは、キャッチオールの/source\/(.*)/ではなく/source\/(.+?\.html).*/に一致します。これにより、index.html.hamlではなくindex.htmlという公開パスが生成されます。

マップ先ページを表示する

ルートマップを使用すると、ソースファイルからレビューアプリ内の対応するページに直接移動できます。

前提要件:

• .gitlab/route-map.ymlでルートマップを設定している必要があります。
• ブランチまたはマージリクエストにレビューアプリがデプロイされている必要があります。

マージリクエストウィジェットからマップ先ページを表示するには、次のようにします:

1. マージリクエストウィジェットで、アプリを表示を選択します。ドロップダウンリストには、最大5件のマップ先ページが表示されます（それより多い場合はフィルタリングされます）。

ファイルからマップ先ページを表示するには、次のようにします:

1. 次のいずれかの方法で、ルートマップに一致するファイルに移動します:
   • マージリクエストから: 変更タブで、View file @ [commit]（ファイルを表示 @ [コミット]）を選択します。
   • コミットページから: ファイル名を選択します。
   • 比較から: リビジョンを比較する際にファイル名を選択します。
2. ファイルのページで、右上隅にあるView on [environment-name]（環境名]で表示）（ ）を選択します。

コミットからマップ先ページを表示するには、次のようにします:

1. レビューアプリがデプロイされているコミットに移動します:
   • ブランチパイプライン: コード > コミットを選択し、パイプラインバッジのあるコミットを選択します。
   • マージリクエストパイプライン: マージリクエストでコミットタブを選択し、コミットを選択します。
   • マージ結果パイプライン: マージリクエストでパイプラインタブを選択し、パイプラインコミットを選択します。
2. ルートマップに一致するファイル名の横にあるレビューアプリアイコン（ ）を選択します。そのアイコンを選択すると、レビューアプリ内で対応するページが開きます。