Docs route maps
This commit is contained in:
parent
c94ce6fe51
commit
ec564163d4
|
@ -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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
![View app file list in merge request widget](img/view_on_mr_widget.png)
|
||||
|
||||
- In the diff for a merge request, comparison, or commit.
|
||||
|
||||
!["View on env" button in merge request diff](img/view_on_env_mr.png)
|
||||
|
||||
- In the blob file view.
|
||||
|
||||
!["View on env" button in file view](img/view_on_env_blob.png) |
|
||||
|
||||
---
|
||||
|
||||
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
|
||||
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
|
||||
|
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 12 KiB |
Before Width: | Height: | Size: 288 KiB After Width: | Height: | Size: 288 KiB |
Before Width: | Height: | Size: 21 KiB After Width: | Height: | Size: 21 KiB |
|
@ -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.
|
||||
|
||||
![View app file list in merge request widget](img/view_on_mr_widget.png)
|
||||
|
||||
- In the diff for a merge request, comparison, or commit.
|
||||
|
||||
!["View on env" button in merge request diff](img/view_on_env_mr.png)
|
||||
|
||||
- In the blob file view.
|
||||
|
||||
!["View on env" button in file view](img/view_on_env_blob.png)
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
Loading…
Reference in New Issue