If you already have Continuous Integration and Continuous Delivery enabled for your websites, adding this feature is blazing fast, and will make life of your reviewers easier! If you want to start with CI/CD in Gitlab, I’ve written about it in the past.

The feature

While the official documentation has a good overview of the feature, we can take a deeper look with some screenshots:

We can comment directly from the staging environment! And additional metadata will be collected and published as well, making easier to reproduce a bug.

Our comment (plus the metadata) appears in the merge request, becoming actionable.

Implementing the system

Adding the snippet isn’t complicate, you only need some information about the MR. Basically, this is what you should add to the head of your website for every merge request:

1<script
2  data-project-id="CI_PROJECT_ID"
3  data-merge-request-id="CI_MERGE_REQUEST_IID"
4  data-mr-url='https://gitlab.example.com'
5  data-project-path="CI_PROJECT_PATH"
6  id='review-app-toolbar-script'
7  src='https://gitlab.example.com/assets/webpack/visual_review_toolbar.js'>
8</script>

Of course, asking your team to add the HTML snippet, and filling it with the right information isn’t feasible. We will instead take advantage of Gitlab CI/CD to inject the snippet and autocomplete it with the right information for every merge request.

First we need the definition of a Gitlab CI job to build our client:

 1buildClient:
 2  image: node:12
 3  stage: build
 4  script:
 5    - ./scripts/inject-review-app-index.sh
 6    - npm ci
 7    - npm run build
 8  artifacts:
 9    paths:
10      - build
11  only:
12    - merge_requests
13  cache:
14    paths:
15      - .npm

The important bit of information here is only: merge_requests. When used, Gitlab injects in the job a environment variable, called CI_MERGE_REQUEST_IID, with the unique ID of the merge request: we will fill it in the HTML snippet. The official documentation of Gitlab CI explains in detail all the other keywords of the YAML.

The script

The other important bit is the script that actually injects the code: it’s a simple bash script, which looks for the </title> tag in the HTML, and append the needed snippet:

 1#!/bin/sh
 2
 3repl() {
 4  PATTERN=$1 REPL=$2 awk '
 5    {gsub(ENVIRON["PATTERN"], ENVIRON["REPL"]); print}'
 6}
 7
 8TEXT_TO_INJECT=$(cat <<-HTML
 9</title>
10<script
11  data-project-id="${CI_PROJECT_ID}"
12  data-merge-request-id="${CI_MERGE_REQUEST_IID}"
13  data-mr-url='${CI_SERVER_URL}'
14  data-project-path="${CI_PROJECT_PATH}"
15  id='review-app-toolbar-script'
16  src='${CI_SERVER_URL}/assets/webpack/visual_review_toolbar.js'>
17</script>
18HTML
19)
20
21repl "</title>" "${TEXT_TO_INJECT}" < public/index.html > tmpfile && mv tmpfile public/index.html

Thanks to the Gitlab CI environment variables, the snippet has already all the information it needs to work. Of course you should customize the script with the right path for your index.html (or any other page you have).

Now everything is ready! Your team needs only to generate personal access tokens to login, and they are ready to go! You should store your personal access token in your password manager, so you don’t need to generate it each time.

Future features

One of the coolest things in Gitlab is that everything is always a work in progress, and each feature has some new goodies in every release. This is true for the Visual Reviews App as well. There is an epic that collects all the improvements they want to do, including removing the need for an access token, and adding ability to take screenshots that will be inserted in the MR comments as well.

That’s all for today, I hope you found this article useful! For any comment, feedback, critic, leave a comment below, or drop an email at [email protected].

I have also changed the blog theme to a custom version of Rapido.css. I think it increases the readability, but let me know what you think!

Ciao,
R.