Configuring GitLab Pages to Get the Preview I Want

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 . I'm using GitLab Pages, and there's no such out-of-the-box feature. Vercel's preview 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 . It's an improvement, even if not the panacea. DocGist 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 , 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. attach the images to the gist 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. -- GitLab Pages 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 stages: - preview preview: stage: preview image: 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 artifacts: paths: - public only: refs: - preview variables: JEKYLL_ENV: production At this point, the site is available at . Many issues need fixing, though. https://$CI_PROJECT_NAMESPACE.gitlab.io/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html Making it work Let's fix the issues by order of importance. Fixing access permissions The project is ; hence, only I can access the artifact: it defeats the initial purpose of offering the preview to others. private I want to give my teammates only limited access to my GitLab repository. I gave them , according to the . However, it still didn't work. Guest access Principle of least privilege As per the documentation, you must also make your pipeline . Go to Settings > CI/CD > General pipelines and check the Public pipelines checkbox. public Fixing relative links I use to build HTML from Asciidoc. To generate links, Jekyll uses two configuration parameters: Jekyll The domain, , , set with e.g. https://blog.frankel.ch url The path, , , set with e.g. / baseurl 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: preview: stage: preview image: name: registry.gitlab.com/nfrankel/nfrankel.gitlab.io:latest before_script: - 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 Set using the environment variable. I could have used a hard-coded value since it's static, but it makes the script more reusable url CI_PROJECT_NAMESPACE Set using the and environment variables. The latter is the random part of the requirement baseurl CI_PROJECT_NAME CI_JOB_ID Display the configuration's content for debugging purposes 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 , they will serve the root . 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. https://blog.frankel.ch index.html Usage At this point, I only need to push to my branch: preview 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. Conclusion 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. To go further: GitLab CI/CD permissions Set artifacts visibility independent of the project or group visibility Change which users can view your pipelines Originally at on June 4th, 2023 published A Java Geek