From 4b21dc0c5156283e82786e24a69373f8b7727f8e Mon Sep 17 00:00:00 2001 From: Lysanne Pinto Date: Wed, 9 Jul 2025 17:06:42 -0400 Subject: [PATCH 1/4] Add missing route map access methods for review apps --- doc/ci/review_apps/_index.md | 54 +++++++++++++++++++++++------------- 1 file changed, 35 insertions(+), 19 deletions(-) diff --git a/doc/ci/review_apps/_index.md b/doc/ci/review_apps/_index.md index bf310b45a4f558..b63c6aba7400cf 100644 --- a/doc/ci/review_apps/_index.md +++ b/doc/ci/review_apps/_index.md @@ -266,8 +266,8 @@ Other examples of review apps: Route maps let you navigate directly from source files to their corresponding public pages in the review app environment. This feature makes it easier to preview specific changes in your merge requests. -When configured, route maps enhance the review app experience by adding links to review app versions -of the changed files in: +When configured, route maps add contextual links that let you view the review app version of files +that match your mapping patterns. These links appear in: - The merge request widget. - Commit and file views. @@ -290,8 +290,8 @@ Each mapping in the route map follows this format: You can use two types of mapping: -- **Exact match**: String literals enclosed in single quotes -- **Pattern match**: Regular expressions enclosed in forward slashes +- Exact match: String literals enclosed in single quotes +- Pattern match: Regular expressions enclosed in forward slashes For pattern matching with regular expressions: @@ -332,25 +332,41 @@ In this example: ### View mapped pages -After you configure route maps, you can find links to the mapped pages after the next -review app deployment. +Use route maps to navigate directly from source files to their corresponding pages in your review app. -To view mapped pages: +Prerequisites: + +- You must have configured route maps in `.gitlab/route-map.yml`. +- A review app must be deployed for your branch or merge request. + +To view mapped pages from the merge request widget: + +1. In the merge request widget, select **View app**. + The dropdown list shows up to 5 mapped pages (with filtering if more are available). -- In the merge request widget, select **View app** to go to the environment URL set in the - `.gitlab-ci.yml` file. The list shows up to 5 matched items from the route map (with - filtering if more are available). +![Merge request widget with route maps showing matched items and filter bar.](img/mr_widget_route_maps_v17_11.png) - ![Merge request widget with route maps showing matched items and filter bar](img/mr_widget_route_maps_v17_11.png) +To view a mapped page from a file: -For files in your route map: +1. Navigate to a file that matches your route map using one of these methods: + - From a merge request: In the **Changes** tab, select **View file @ [commit]**. + - From a commit page: Select the file name. + - From a comparison: When comparing revisions, select the file name. +1. On the file's page, select **View on [environment-name]** ({{< icon name="external-link" >}}) in the upper-right corner. -1. In the **Changes** tab of your merge request, select **View file @ [commit]** next to a file. -1. On the file's page, look for **View on [deployment-URL]** ({{< icon name="external-link" >}}) in the upper-right corner. +To view mapped pages from commits: -For merge requests using merged results pipelines: +1. Navigate to a commit that has a review app deployment: + - For branch pipelines: Select **Code > Commits** and select a commit with a pipeline badge. + - For regular merge request pipelines: In your merge request, select the **Commits** tab and select a commit. + - For merged results pipelines: In your merge request, select the **Pipelines** tab and select the pipeline commit. +1. Files matching your route map display a review app icon ({{< icon name="external-link" >}}) next to the file name. +1. Select the icon to open the corresponding page in your review app. -1. Go to the **Pipelines** tab in your merge request. -1. Select the commit for the latest pipeline. -1. Select **View file @ [commit]** next to a file. -1. On the file's page, select **View on [deployment-URL]** ({{< icon name="external-link" >}}) in the upper-right corner. +{{< alert type="note" >}} + +Merged results pipelines create an internal commit that merges your branch with the target branch. +To access review app links for these pipelines, use the commit from the **Pipelines** tab, +not the **Commits** tab. + +{{< /alert >}} -- GitLab From 6ddb657206feb3bf91197800a920800f5b9cf399 Mon Sep 17 00:00:00 2001 From: Lysanne Pinto Date: Wed, 9 Jul 2025 17:15:56 -0400 Subject: [PATCH 2/4] Edit to align with word list https://docs.gitlab.com/development/documentation/styleguide/word_list/#filename --- doc/ci/review_apps/_index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/ci/review_apps/_index.md b/doc/ci/review_apps/_index.md index b63c6aba7400cf..de4f11cb3caa5b 100644 --- a/doc/ci/review_apps/_index.md +++ b/doc/ci/review_apps/_index.md @@ -350,8 +350,8 @@ To view a mapped page from a file: 1. Navigate to a file that matches your route map using one of these methods: - From a merge request: In the **Changes** tab, select **View file @ [commit]**. - - From a commit page: Select the file name. - - From a comparison: When comparing revisions, select the file name. + - From a commit page: Select the filename. + - From a comparison: When comparing revisions, select the filename. 1. On the file's page, select **View on [environment-name]** ({{< icon name="external-link" >}}) in the upper-right corner. To view mapped pages from commits: @@ -360,7 +360,7 @@ To view mapped pages from commits: - For branch pipelines: Select **Code > Commits** and select a commit with a pipeline badge. - For regular merge request pipelines: In your merge request, select the **Commits** tab and select a commit. - For merged results pipelines: In your merge request, select the **Pipelines** tab and select the pipeline commit. -1. Files matching your route map display a review app icon ({{< icon name="external-link" >}}) next to the file name. +1. Files matching your route map display a review app icon ({{< icon name="external-link" >}}) next to the filename. 1. Select the icon to open the corresponding page in your review app. {{< alert type="note" >}} -- GitLab From 1c2e50baf00ba34c0d606f019e743ffe975768f8 Mon Sep 17 00:00:00 2001 From: Lysanne Pinto Date: Wed, 9 Jul 2025 17:31:34 -0400 Subject: [PATCH 3/4] Combines task steps --- doc/ci/review_apps/_index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/ci/review_apps/_index.md b/doc/ci/review_apps/_index.md index de4f11cb3caa5b..1d7de13388a0b0 100644 --- a/doc/ci/review_apps/_index.md +++ b/doc/ci/review_apps/_index.md @@ -354,14 +354,14 @@ To view a mapped page from a file: - From a comparison: When comparing revisions, select the filename. 1. On the file's page, select **View on [environment-name]** ({{< icon name="external-link" >}}) in the upper-right corner. -To view mapped pages from commits: +To view mapped pages from a commit: 1. Navigate to a commit that has a review app deployment: - For branch pipelines: Select **Code > Commits** and select a commit with a pipeline badge. - - For regular merge request pipelines: In your merge request, select the **Commits** tab and select a commit. + - For merge request pipelines: In your merge request, select the **Commits** tab and select a commit. - For merged results pipelines: In your merge request, select the **Pipelines** tab and select the pipeline commit. -1. Files matching your route map display a review app icon ({{< icon name="external-link" >}}) next to the filename. -1. Select the icon to open the corresponding page in your review app. +1. Select the review app icon ({{< icon name="external-link" >}}) next to a filename that matches your route map. + The icon opens the corresponding page in your review app. {{< alert type="note" >}} -- GitLab From 5a74de491f446938d140d73c251721c36cd76bb4 Mon Sep 17 00:00:00 2001 From: Lysanne Pinto Date: Wed, 9 Jul 2025 17:51:55 -0400 Subject: [PATCH 4/4] Replace navigate with go to --- doc/ci/review_apps/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/ci/review_apps/_index.md b/doc/ci/review_apps/_index.md index 1d7de13388a0b0..77c91027dd8f2f 100644 --- a/doc/ci/review_apps/_index.md +++ b/doc/ci/review_apps/_index.md @@ -348,7 +348,7 @@ To view mapped pages from the merge request widget: To view a mapped page from a file: -1. Navigate to a file that matches your route map using one of these methods: +1. Go to a file that matches your route map using one of these methods: - From a merge request: In the **Changes** tab, select **View file @ [commit]**. - From a commit page: Select the filename. - From a comparison: When comparing revisions, select the filename. @@ -356,7 +356,7 @@ To view a mapped page from a file: To view mapped pages from a commit: -1. Navigate to a commit that has a review app deployment: +1. Go to a commit that has a review app deployment: - For branch pipelines: Select **Code > Commits** and select a commit with a pipeline badge. - For merge request pipelines: In your merge request, select the **Commits** tab and select a commit. - For merged results pipelines: In your merge request, select the **Pipelines** tab and select the pipeline commit. -- GitLab