DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Please enter at least three characters to search
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

The software you build is only as secure as the code that powers it. Learn how malicious code creeps into your software supply chain.

Apache Cassandra combines the benefits of major NoSQL databases to support data management needs not covered by traditional RDBMS vendors.

Generative AI has transformed nearly every industry. How can you leverage GenAI to improve your productivity and efficiency?

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workloads.

Related

  • CI/CD Pipelines for Kubernetes Using GitLab CI
  • Pipeline as a Service: How To Test Pipelines in GitLab
  • How to Set Up GitLab Notifications in Telegram: A Comprehensive Tutorial
  • How To Use GitLab for Simultaneous Execution of Jobs (Part 2)

Trending

  • FIPS 140-3: The Security Standard That Protects Our Federal Data
  • Scaling DevOps With NGINX Caching: Reducing Latency and Backend Load
  • Beyond Simple Responses: Building Truly Conversational LLM Chatbots
  • Agentic AI for Automated Application Security and Vulnerability Management
  1. DZone
  2. Testing, Deployment, and Maintenance
  3. Deployment
  4. GitLab Pages Preview

GitLab Pages Preview

In this post, the author describes how they configured GitLab Pages to get the preview they want, and the process of getting there.

By 
Nicolas Fränkel user avatar
Nicolas Fränkel
DZone Core CORE ·
Jun. 08, 23 · Tutorial
Likes (3)
Comment
Save
Tweet
Share
3.1K Views

Join the DZone community and get the full member experience.

Join For Free

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.

-- 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:

YAML
 
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 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.

Fixing Relative Links

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

  • The domain, e.g., , set with url
  • The path, e.g., /, set with 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:

YAML
 
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


  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:

YAML
 
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.

Usage

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

Shell
 
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
GitLab AsciiDoc

Published at DZone with permission of Nicolas Fränkel, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • CI/CD Pipelines for Kubernetes Using GitLab CI
  • Pipeline as a Service: How To Test Pipelines in GitLab
  • How to Set Up GitLab Notifications in Telegram: A Comprehensive Tutorial
  • How To Use GitLab for Simultaneous Execution of Jobs (Part 2)

Partner Resources

×

Comments
Oops! Something Went Wrong

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends:

Likes
There are no likes...yet! 👀
Be the first to like this post!
It looks like you're not logged in.
Sign in to see who liked this post!