The Ultimate Manual To GitLab Pages

GitLab Pages is a GitLab initiative to help users create websites for their GitLab projects, groups, and user accounts. It lets you host your static websites on GitLab.com for free—or even on your own GitLab Enterprise edition instance.

In this guide, we’ll explore GitLab Pages in more detail, plus share a step-by-step rundown to help you create a GitLab Pages website.

What is GitLab Pages Anyway?

GitLab Pages lets you publish static websites from the repository in GitLab. It serves a variety of purposes, including:

Use for any personal or business website
Use any Static Site Generator (SSG) or plain HTML
Create a website for your projects, groups, user accounts
Create a website on your own GitLab instance or on GitLab.com free of cost
Connect your custom domains and TLS certificates
Attribute any license to your content

To be able to publish a website with GitLab Pages, you’ll need a Static Site Generator (e.g., Jekyll, Middleman, Gatsby, Hugo, Brunch, or Harp). You can also publish websites written directly in plain HTML, JavaScript, and CSS.

Website Types

You can create and host two kinds of websites with GitLab Pages:

User/group website — Single site per user or group
Project website — As many sites you want

How GitLab Pages Works

To use GitLab Pages, you have to first create a project, regardless of whether it’s public, private, or internal, in GitLab to upload your website files. GitLab Pages will always deploy your website from a specific folder called public in your repository. Whenever you create a new project, a repository will automatically become available in GitLab.

To deploy your site, GitLab will use its built-in tool called GitLab CI/CD to build your website and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to achieve this task is created from a special file called .gitlab-ci.yml, which can be created and modified.

This is also where you need to know about a specific job called pages in the configuration file, which makes GitLab aware you are deploying a GitLab Pages website.

For this, you can either use the GitLab default domain for GitLab Pages websites, *.gitlab.io, or your own domain (e.g., abc.com). Keep in mind that you need to be the administrator in your domain registrar or control plan panel to set it up with pages.

GitLab Pages Brief Rundown

While we’ll be covering the step-by-step rundown in more detail later in the article, here’s a quick rundown of how you can use GitLab Pages:

For the sake of this article, we’ll assume you’ll fork one of GitLab’s example projects instead of creating a project from scratch. You can choose any Static Site Generator since GitLab Pages is compatible with all.

Next, you have to enable shed runners. We recommend taking advantage of the free shared Runners available on GitLab.com, where all your builds will run on distinct Virtual Machines that use the latest Docker Engine. Since there will be no potential breaking outside the container, this eliminates any security issues effectively. However, this is just a suggestion, and you can always set up your own runner for your project.

Next comes project configuration, which is an optional step. If you don’t configure your project, your website will be available at https://username.gitlab.io/projectname, where username will be your username on GitLab and projectname will be the name of the project you forked in the first step. This is also known as the project page.

Once that is done, you have to manually run a pipeline for the first time to trigger the job success. Alternatively, you can commit and push at least one change. Editing your site files right from the browser is possible, but you can also use Git from the command line if you want.

After the above, you can finally visit your store. Simply fire up your browser and visit https://username.gitlab.io/projectname or https://username.gitlab.io, depending on whether you configured your project or not.

GitLab Pages Examples

You can check out the Pages official group for a list of example projects. This can be a good place to explore options for Static State Generators for Ruby, Python, and NodeJS environments.

Here’s a list of more specific examples to start:

How to Create a GitLab Pages Website

Before we get started with the tutorial, make sure you have a blank project in GitLab. Now, let’s take a look at how you can create a GitLab Pages website.

Step 1: Create the Project Files

Create three files in the top-level or root directory.

.gitlab-ci.yml: This is a YAML file that will contain the commands you want to run. Leave the file contents blank for now.
index.html: This is an HTML file you can populate with any kind of HTML content you want.
Gemfile: This file describes dependencies for Ruby programs. Populate it with the following:

source “https://rubygems.org”

gem “jekyll”

Step 2: Choose a Docker Image

The runner will use a Docker image to run scripts and deploy the site, while the Ruby image is maintained on DockerHub.

Edit your .gitlab-ci.yml file and add the following text as the first line:

image: ruby:2.7

If your SSG needs NodeJS to build, be sure to specify an image that contains NodeJS as part of its file system.

Step 3: Install Jekyll

Before running Jekyll locally, you’ll have to install it. Here are the steps to do it:

Open your terminal and install Bundler by running gem install bundler.
Run bundle install to create Gemfile.lock.
Install Jekyll by running bundle exec jekyll build.

For running Jekyll in your project, you’ll have to edit the .gitlab-ci.yml file and add the following installation commands:

script:

– gem install bundler

– bundle install

– bundle exec jekyll build

Interestingly, each script in the .gitlab-ci.yml file is organized by a job. A job includes the scripts and settings you will need to apply for doing that specific task.

Here’s how it will look:

job:

script:

– gem install bundler

– bundle install

– bundle exec jekyll build

For GitLab Pages, this job has a specific name known as pages. This particular setting is important as it tells the runner you want the job to deploy your website with GitLab Pages.

pages:

script:

– gem install bundler

– bundle install

– bundle exec jekyll build

Step 4: Specify the public Directory for Output

Here, you’ll have to specify to Jekyll where to generate its output. Remember, GitLab Pages only considers files in a directory called public.

Jekyll uses a destination flag (-d) to specify an output directory for the built website. Your job is to add a destination to your .gitlab-ci.yml file:

pages:

script:

– gem install bundler

– bundle install

– bundle exec jekyll build -d public

Step 5: Specify the public Directory for Artifacts

At this stage, Jekyll has output the files to the public directory. Now, the runner will need to know where to get them.

As mentioned, the artifacts will be stored in the public directory for a GitLab Pages website. That’s what the artifacts will look like:

pages:

script:

– gem install bundler

– bundle install

– bundle exec jekyll build -d public

artifacts:

paths:

– public

Your .gitlab-ci.yml file should now look like this:

image: ruby:2.7

pages:

script:

– gem install bundler

– bundle install

– bundle exec jekyll build -d public

artifacts:

paths:

– public

Step 6: Deploy and View the GitLab Pages Website

Finally, you can deploy your GitLab Pages website!

Here are the steps to go about this:

Save and commit the .gitlab-ci.yml file.
Go to CI/CD, Followed by pipelines to watch the pipeline.
When the pipeline succeeds, navigate to Settings and click on Pages. View the URL where your site is now available.

Helpful Posts to Navigate GitLab

If you enjoyed this piece and want to explore the fascinating world of GitLab further, we recommend checking out some of the other blog posts we’ve created to help developers.