GitLab Pages preview

When I write Apache APISIX-related blog posts, I want my colleagues to review them first. However, it’s my blog, and since I mix personal and business posts, I want to keep them from the repository. I need a preview, accessible only to a few, something like Vercel’s preview. I’m using GitLab Pages, and there’s no such out-of-the-box feature.

I tried two methods: GitHub gists and PDFs. Both have issues.

Gists don’t display as nicely as the final page. I tried to improve the situation by using DocGist. It’s an improvement, even if not the panacea.

Moreover, gists don’t display images since I write my posts in Asciidoc. I’ve to set images in comments, and it breaks the flow. I’ve tried to attach the images to the gist, but they don’t appear in the flow of the post in any case. The pro over comments is that they are ordered; the con is that I need to change the Asciidoc.

I used gists because I’m used to GitHub reviews. But since it’s my blog, I neither need nor want the same kind of reviews as in a regular Merge Request. I need people to point me to when something needs to be clarified, or I missed a logical jump, not that I made a typo (I use Grammarly for this). For this reason, a PDF export of a post is enough to review.

However, PDFs have issues on their own: a web "page" is potentially endless, while a regular PDF page cuts the former into standard pages. Splits can happen across diagrams. Besides, PDFs make distribution much harder.

In this post, I’ll describe how I configured GitLab Pages to get the preview I want.

Summary of GitLab Pages

GitLab Pages are akin to GitHub Pages:

With GitLab Pages, you can publish static websites directly from a repository in GitLab.

To publish a website with Pages, you can use any static site generator, like Gatsby, Jekyll, Hugo, Middleman, Harp, Hexo, or Brunch. You can also publish any website written directly in plain HTML, CSS, and JavaScript.

That’s how you see this blog post. I found no preview feature for GitLab Pages. I asked experts to no avail; GitLab doesn’t offer previews.

Laying out the work

I didn’t believe it initially, but you only need to create a dedicated artifact. Since the artifact consists of web files, the browser will render them.

The idea is to create such an artifact, accessible under an URL, which cannot be easily predicted. I can then share the URL with my colleagues and ask for their review. To start with, we can copy the existing build on master:

  - preview

  stage: preview
    name: registry.gitlab.com/nfrankel/nfrankel.gitlab.io:latest
  before_script: cd /builds/nfrankel/nfrankel.gitlab.io
  script: bundle exec jekyll b --future -t --config _config.yml -d public
      - public
      - preview
    JEKYLL_ENV: production

At this point, the site is available at https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html. Many issues need fixing, though.

Making it work

Let’s fix the issues by order of importance.

Fixing access permissions

The project is private; hence, only I can access the artifact: it defeats the initial purpose of offering the preview to others.

I want to give my teammates only limited access to my GitLab repository. I gave them Guest access, according to the Principle of least privilege. However, it still didn’t work.

As per the documentation, you must also make your pipeline public. Go to Settings  CI/CD  General pipelines and check the Public pipelines checkbox.

I use Jekyll to build HTML from Asciidoc. To generate links, Jekyll uses two configuration parameters:

Both are different on the preview. You must set those parameters in a YAML configuration file; there’s no environment variable alternative.

Let’s change the build accordingly:

  stage: preview
    name: registry.gitlab.com/nfrankel/nfrankel.gitlab.io:latest
    - cd /builds/nfrankel/nfrankel.gitlab.io
    - "printf 'url: https://%s.gitlab.io\n' $CI_PROJECT_NAMESPACE >> _config_preview.yml"                        (1)
    - "printf 'baseurl: /-/%s/-/jobs/%s/artifacts/public/\n' $CI_PROJECT_NAME $CI_JOB_ID >> _config_preview.yml" (2)
    - cat _config_preview.yml                                                                                    (3)
  script: bundle exec jekyll b --future -t --config _config.yml,_config_preview.yml -d public                    (4)
1 Set url using the CI_PROJECT_NAMESPACE environment variable. I could have used a hard-coded value since it’s static, but it makes the script more reusable
2 Set baseurl using the CI_PROJECT_NAME and CI_JOB_ID environment variables. The latter is the random part of the requirement
3 Display the configuration’s content for debugging purposes
4 Use it!

Improving usability

It’s a bore trying to distribute the correct URL each time. Better to write it down in the console after building:

after_script: echo https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html

There’s still one missing bit. GitLab Pages offer an index page. For example, if you request https://blog.frankel.ch, they will serve the root index.html. With plain artifacts, it’s not the case. Given that I only want to offer a single post for preview, it’s not an issue, so I didn’t research the configuration further.


At this point, I only need to push to my preview branch:

git push --force origin HEAD:preview

Icing on the cake, we don’t need to have the branch locally; just push to the remote one.


In this post, I showed how to preview GitLab Pages and share the preview’s URL with teammates in a couple of steps. The hardest part was to realize that web artifacts are rendered regularly with the browser.

Nicolas Fränkel

Nicolas Fränkel

Developer Advocate with 15+ years experience consulting for many different customers, in a wide range of contexts (such as telecoms, banking, insurances, large retail and public sector). Usually working on Java/Java EE and Spring technologies, but with focused interests like Rich Internet Applications, Testing, CI/CD and DevOps. Also double as a trainer and triples as a book author.

Read More
GitLab Pages preview
Share this