diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ci/environments.md | 84 | ||||
| -rw-r--r-- | doc/ci/review_apps/img/view_on_env_blob.png (renamed from doc/ci/img/view_on_env_blob.png) | bin | 11889 -> 11889 bytes | |||
| -rw-r--r-- | doc/ci/review_apps/img/view_on_env_mr.png (renamed from doc/ci/img/view_on_env_mr.png) | bin | 295181 -> 295181 bytes | |||
| -rw-r--r-- | doc/ci/review_apps/img/view_on_mr_widget.png (renamed from doc/ci/img/view_on_mr_widget.png) | bin | 21942 -> 21942 bytes | |||
| -rw-r--r-- | doc/ci/review_apps/index.md | 85 | ||||
| -rw-r--r-- | doc/user/project/merge_requests/index.md | 6 |
6 files changed, 99 insertions, 76 deletions
diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 010c579b83e..b9b5ceab7fb 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -416,81 +416,15 @@ and/or `production`) you can see this information in the merge request itself. ### Go directly from source files to public pages on the environment -> Introduced in GitLab 8.17. In GitLab 11.5 the file links -are surfaced to the merge request widget. - -You can specify a Route Map to get GitLab to show **View on ...** -buttons to go directly from a file to that file's representation on the -[deployed website via Review Apps](review_apps/index.md). - -To get this to work, you need to tell GitLab how the paths of files in your repository map to paths of pages on your website, using a Route Map. - -A Route Map is a file inside the repository at `.gitlab/route-map.yml`, which contains a YAML array that maps `source` paths (in the repository) to `public` paths (on the website). -Below is an example of a route map for [Middleman](https://middlemanapp.com) static websites -like <https://gitlab.com/gitlab-com/www-gitlab-com>: - -```yaml -# 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 -``` - -Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, we have a hash map with two keys: - -- `source` - - a string, starting and ending with `'`, for an exact match - - a regular expression, starting and ending with `/`, for a pattern match - - The regular expression needs to match the entire source path - `^` and `$` anchors are implied. - - Can include capture groups denoted by `()` that can be referred to in the `public` path. - - Slashes (`/`) can, but don't have to, be escaped as `\/`. - - Literal periods (`.`) should be escaped as `\.`. -- `public` - - a string, starting and ending with `'`. - - Can include `\N` expressions to refer to capture groups in the `source` regular expression in order of their occurrence, starting with `\1`. - -The public path for a source path is determined by finding the first `source` expression that matches it, and returning the corresponding `public` path, replacing the `\N` expressions with the values of the `()` capture groups if appropriate. - -In the example above, the fact that mappings are evaluated in order of their definition is used to ensure that `source/index.html.haml` will match `/source\/(.+?\.html).*/` instead of `/source\/(.*)/`, and will result in a public path of `index.html`, instead of `index.html.haml`. - ---- - -Once you have the route mapping set up, it will be exposed in a few places: - -- In the merge request widget. The **View app** button will take you to the - environment URL you have set up in `.gitlab-ci.yml`. The dropdown will render - the first 5 matched items from the route map, but you can filter them if more - than 5 are available. - -  - -- In the diff for a merge request, comparison, or commit. - -  - -- In the blob file view. - -  | - ---- - -We now have a full development cycle, where our app is tested, built, deployed -as a Review app, deployed to a staging server once the merge request is merged, -and finally manually deployed to the production server. What we just described -is a single workflow, but imagine tens of developers working on a project -at the same time. They each push to their branches, and dynamic environments are -created all the time. In that case, we probably need to do some clean up. Read +With GitLab's [Route Maps](review_apps/index.md#route-maps) you can go directly +from source files to public pages on the environment set for Review Apps. + +From then on, you have a full development cycle, where your app is tested, built, deployed +as a Review App, deployed to a staging server once the merge request is merged, +and finally manually deployed to the production server. This is a simple workflow, +but when you have multiple developers working on a project +at the same time, each of them pushing to their own branches, dynamic environments are +created all the time. In which case, you probably want to do some clean up. Read next how environments can be stopped. ## Stopping an environment diff --git a/doc/ci/img/view_on_env_blob.png b/doc/ci/review_apps/img/view_on_env_blob.png Binary files differindex acc457fbb38..acc457fbb38 100644 --- a/doc/ci/img/view_on_env_blob.png +++ b/doc/ci/review_apps/img/view_on_env_blob.png diff --git a/doc/ci/img/view_on_env_mr.png b/doc/ci/review_apps/img/view_on_env_mr.png Binary files differindex 2c0bd25a4f2..2c0bd25a4f2 100644 --- a/doc/ci/img/view_on_env_mr.png +++ b/doc/ci/review_apps/img/view_on_env_mr.png diff --git a/doc/ci/img/view_on_mr_widget.png b/doc/ci/review_apps/img/view_on_mr_widget.png Binary files differindex efe023b07b5..efe023b07b5 100644 --- a/doc/ci/img/view_on_mr_widget.png +++ b/doc/ci/review_apps/img/view_on_mr_widget.png diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 64be011008e..8b3a7b63e62 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -102,3 +102,88 @@ The following are example projects that use Review Apps with: - [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift). See also the video [Demo: Cloud Native Development with GitLab](https://www.youtube.com/watch?v=jfIyQEwrocw), which includes a Review Apps example. + +## Route Maps + +> Introduced in GitLab 8.17. In GitLab 11.5 the file links +are surfaced to the merge request widget. + +Route Maps allows you to go directly from source files +to public pages on the [environment](../environments.md) defined for +Review Apps. Once set up, the review app link in the merge request +widget can take you directly to the pages changed, making it easier +and faster to preview proposed modifications. + +All you need to do is to tell GitLab how the paths of files +in your repository map to paths of pages on your website using a Route Map. +Once set, GitLab will display **View on ...** buttons, which will take you +to the pages changed directly from merge requests. + +To set up a route map, add a a file inside the repository at `.gitlab/route-map.yml`, +which contains a YAML array that maps `source` paths (in the repository) to `public` +paths (on the website). + +### Route Maps example + +Below there's an example of a route map for [Middleman](https://middlemanapp.com), +a static site generator (SSG) used to build [GitLab's website](https://about.gitlab.com), +deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitlab-com): + +```yaml +# 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 +``` + +Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, we have a hash map with two keys: + +- `source` + - a string, starting and ending with `'`, for an exact match + - a regular expression, starting and ending with `/`, for a pattern match + - The regular expression needs to match the entire source path - `^` and `$` anchors are implied. + - Can include capture groups denoted by `()` that can be referred to in the `public` path. + - Slashes (`/`) can, but don't have to, be escaped as `\/`. + - Literal periods (`.`) should be escaped as `\.`. +- `public` + - a string, starting and ending with `'`. + - Can include `\N` expressions to refer to capture groups in the `source` regular expression in order of their occurrence, starting with `\1`. + +The public path for a source path is determined by finding the first +`source` expression that matches it, and returning the corresponding +`public` path, replacing the `\N` expressions with the values of the +`()` capture groups if appropriate. + +In the example above, the fact that mappings are evaluated in order +of their definition is used to ensure that `source/index.html.haml` +will match `/source\/(.+?\.html).*/` instead of `/source\/(.*)/`, +and will result in a public path of `index.html`, instead of +`index.html.haml`. + +Once you have the route mapping set up, it will be exposed in a few places: + +- In the merge request widget. The **View app** button will take you to the + environment URL you have set up in `.gitlab-ci.yml`. The dropdown will render + the first 5 matched items from the route map, but you can filter them if more + than 5 are available. + +  + +- In the diff for a merge request, comparison, or commit. + +  + +- In the blob file view. + +  diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 9015a964781..2c8a590fc45 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -284,7 +284,11 @@ you can preview the changes submitted to a feature-branch through a merge reques in a per-branch basis. No need to checkout the branch, install and preview locally; all your changes will be available to preview by anyone with the Review Apps link. -[Read more about Review Apps.](../../../ci/review_apps/index.md) +With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the +merge request widget takes you directly to the pages changed, making it easier and +faster to preview proposed modifications. + +[Read more about Review Apps](../../../ci/review_apps/index.md). ## Pipelines for merge requests |
