Hosting on GitLab.com with GitLab Pages

Apr 7, 2016

In this article we provide you with detailed information about using GitLab Pages to host your website for free on GitLab.com.

We've prepared a step-by-step tutorial on creating a new project for GitLab Pages so you won't get lost in the process.

GitLab Pages supports static websites and builds any Static Site Generator (SSG), such as Jekyll, Hugo, Hexo, Middleman and Pelican.

We are assuming that you are familiar with Git and with the web development process, from creation to publishing.


What's in this tutorial?


Getting Started

There are two ways of getting started with GitLab Pages: either you fork an existing project, or you create a new one for yourself.

On the GitLab Pages Quick Start Guide, which is, by the way, a site built with Middleman, you will find the steps for forking an existing project from a list of examples prepared for you. There are some popular SSGs, like Jekyll, Hugo, Hexo, Bruch, etc.

However, if you want to understand the process of creating a new project from scratch, this post is for you.

On the official documentation you can learn about GitLab Pages, but here we will focus on the steps for creating your own project.

Note: GitLab Pages was introduced in GitLab EE 8.3. It is available for GitLab.com and GitLab Enterprise Edition users.

Website Types

In general, you are allowed to create and host two sorts of websites with GitLab Pages:

  1. User/Group Websites - a single site per user or group
  2. Project Websites - as many sites you want

You can find out more about them on the docs.

A note regarding GitLab Groups and Namespaces

Creating a group on GitLab is very useful when you have several projects with the same subject. A group has its own namespace, which is unique for each group (and for each user).

The important matter is, when you create your account on GitLab, it's better to choose a username for yourself as a person, not as a company. You can create your "company username" later, as a group namespace. For example, let's say your name is "John Doe" and your company is called "Foo Master". First, register yourself as johndoe and later create a group called Foo Master within the namespace of foomaster. This will allow you to separate your personal projects from your company ones.

If you follow this tip, you will be able to access your personal site under https://username.gitlab.io and your company site under https://groupname.gitlab.io.

About GitLab CI for GitLab Pages

The key to having everything up and running as expected is the GitLab CI configuration file, called .gitlab-ci.yml.

This file configures how your website will be built by a Runner. It is written in YAML, which has its own syntax, so we recommend you follow this quick start guide before setting it up. It needs to be placed at your root directory.

The most important fact is that with GitLab CI, you take control over your builds. They won't be in an invisible black box where you don't know what is going on! You can actually see any build running live by navigating to your project's Pipelines > Builds > Build ID. You can also add any command to your script. This is far beyond useful as it allows you to do pretty much anything you do on your local machine!

For example, you can add any Jekyll Plugin to your Jekyll site, you can require any gem you need in your Gemfile, run npm, run bundle and much more. Bottom line, it's as handy as having your own command line on your GitLab UI.

Additionally, you can have a distinct .gitlab-ci.yml for each repository - even for each branch. This means you can test your script in parallel branches before pushing to your master branch. If the build succeeds, you merge. If it doesn't, you can make adjustments and try building again without messing up your master branch.

Before you push any .gitlab-ci.yml to your project, you can validate its syntax with the tool called CI Lint. You need to be logged into your account to have access to this tool. It's found by navigating to your project's Pipelines: there is a button at the top-right of your screen.

CI-Lint

You can read through the full documentation for .gitlab-ci.yml for more information.

Creating new GitLab Pages projects

Here is an overview of the steps we'll take, assuming you already have your GitLab.com account:

  1. Create a new project
  2. Add the configuration file (.gitlab-ci.yml)
  3. Upload your website content
  4. Add your custom domain (optional)
  5. Done!

Step-by-step

Now we will go through this process step-by-step.

Step 1: Create a new project

This is as straight-forward as you can imagine:

Note: you can host your website on GitLab.com even if it is stored in a private repository. If you do so, you can have your project protected - only the static site will be visible to the public - via "Inspect Element" or "View-Source" from their web browsers.

Step 2: Add the configuration file: .gitlab-ci.yml

Now we can have some fun! Let's tell GitLab CI how to build the site. You will see a few examples below (options A, B, and C) to understand how they work.

Option A: GitLab CI for plain HTML websites

In order to build your plain HTML site with GitLab Pages, your .gitlab-ci.yml file doesn't need much:

pages:
  stage: deploy
  script:
  - mkdir .public
  - cp -r * .public
  - mv .public public
  artifacts:
    paths:
    - public
  only:
  - master

What this code is doing is creating a job called pages telling the Runner to deploy the website artifacts to a public path, whenever a commit is pushed only to the master branch.

All pages are created after the build completes successfully and the artifacts for the pages job are uploaded to GitLab.

Option B: GitLab CI for Jekyll websites

Jekyll is so far the most popular Static Site Generator (SSG) available, that's why we'll use it as a first example for configuring our GitLab CI. On the next section you'll find more examples for SSGs already tested with GitLab Pages.

Jekyll is written in Ruby and generates static blog-aware websites. Blog-aware means a website generator will create blog-style content, such as lists of content in reverse chronological order, archive lists, and other common blog-style features.

We can write dynamically with Liquid, Markdown and YAML and Jekyll builds the static site (HTML, CSS, JS) for us. You will find the same functionality for every SSG, yet each of them uses its own environment, template system, markup language, etc.

If you want GitLab Pages to build your Jekyll website, you can start with the simple script below:

image: ruby:2.1

pages:
  script:
  - gem install jekyll
  - jekyll build -d public/
  artifacts:
    paths:
    - public
  only:
  - master

This code requires the script to run on the environment of Ruby 2.1.x, installs the Jekyll gem, and builds the site to the public path. The result affects only the master branch. For building a regular Jekyll site, you can just copy this code and paste it into your .gitlab-ci.yml.

If you are familiar with Jekyll, you will probably want to use Bundler to build your Jekyll site. We've prepared an example for that. Also, if you want to use a specific Jekyll version, you can find an example in the Jekyll Themes group I set up for the purposes of this post. And of course, since you are the one who controls how GitLab CI builds your site, you are free to use any Jekyll Plugins. Yep!

Option C: GitLab CI for Hexo websites

Let's see another example. Hexo is a powerful blog-aware framework built with NodeJS, a server-side JavaScript environment based on Google V8 high-performance engine.

To build our Hexo site, we can start with this .gitlab-ci.yml:

image: node:4.2.2

pages:
  cache:
    paths:
    - node_modules/

  script:
  - npm install hexo-cli -g
  - npm install
  - hexo deploy
  artifacts:
    paths:
    - public
  only:
    - master

Note that the Docker image we require is node:4.2.2. We are archiving npm modules into the cache, installing hexo-cli and deploying our hexo site to the default public directory, uploaded to GitLab as artifacts. The pages job is only affecting the master branch.

On the Pages group you will find a default Hexo site deployed with GitLab Pages, and on this group, another example with a slightly different configuration.

Step 3: Upload your website content

Push the content to your remote project and keep an eye on the build!

Don't forget: when you are using GitLab Pages with a Static Site Generator, do not upload the directory which your SSG generated locally, otherwise you'll have duplicated contents and you might face build errors. For example, do not commit the _site directory (Jekyll) or the build directory (Middleman) or the public directory (Hexo). You can do this automatically by adding them to a .gitignore file, placed at your project's root directory.

E.g., if you are building a Jekyll site, your .gitignore will have this line:

_site

A .gitignore is very useful to avoid uploading to your remote repository any file or folder within your project. If you want to know more about it, check the .gitignore official docs.

Step 4: Add your custom domain

Note: Custom CNAMEs with TLS support were introduced in GitLab EE 8.5.

If you want, you are free to add your own domain(s) name to your website hosted by GitLab.com. It's not required though, you can always use the standard GitLab Pages subdomain accessed under https://mynamespace.gitlab.io.

Features

Steps to set up a custom domain

mydomain.com A 104.208.235.32

Alternatively, a similar procedure can be applied for custom subdomains:

subdomain.mydomain.com CNAME myusername.gitlab.io

Repeat these steps for any additional domain aliases.

Note that how you set up your DNS records will depend upon which company you used to register your domain name. Every company has its own methods for DNS Zone Management. On this link you can find an overview for some providers, it might help you to follow through. Please contact your provider directly if you need some extra help.

Ordinarily, DNS propagation needs some time to take effect, so don't worry if you can't access your website under your custom domain instantaneously. Wait a few minutes and check it again.

Examples

Check out the Pages official group for a list of example projects, where you can explore some good options for Static Site Generators for Ruby, NodeJS and Python environments. You can also find more specific examples on the following groups, which I prepared for the purposes of this post:

Note: these themes, templates and SSGs were casually chosen and listed on this post to provide you with some distinct GitLab CI configurations.

FAQ

Is all of this really free to use?

Yes, it is! On GitLab.com you can create your free account and enjoy all its features, including unlimited private repositories, projects, websites, and contributors. Also, you'll have 10GB disk space per project, 1GB per Pages artifacts, and unlimited total disk space. Awesome, isn't it? Why don't you take a peek at the public projects?

Where is the public folder?

When a build succeeds, you'll find your static site at your project's Pipelines > Builds > Build ID > Browse. You can download the artifacts from the same screen.

Build Artifacts - Browse or Download

Can I really use any Static Site Generator?

Yes, you can use any Static Site Generator available.

Can I use free SSL/TLS digital certificates?

Yes, absolutely! Need a suggestion? Try StartSSL or Let's Encrypt.

Can I contribute to the themes?

Sure! You are very welcome to contribute to the groups mentioned above. To do that, please set your website up and make sure it's working as you expected. Then, add an issue to the group you're interested in. Don't forget to include a link to your project. After a brief evaluation, we'll be glad to fork your project and present your theme to our community!

Can I use .php pages and connect databases with my sites?

No. GitLab Pages hosts static websites only (HTML, CSS and JS).

Getting Help

If you need some help regarding GitLab Pages on GitLab.com, feel free to use one of our channels. You can also open an issue on the Pages group.

Conclusion

Hopefully now you understand how GitLab Pages works and how to create your new site.

Follow @GitLab on Twitter and stay tuned for updates!

We're looking forward to seeing your sites!

Note: this post has been updated (June 17th, 2016) to match the new GitLab UI.

About guest author Marcia Ramos

Marcia is a back-end developer specialized in WordPress and Jekyll sites at Virtua Creative, though she does some front-end too. Her daily work is based on version-controlled systems for almost 15 years. She is driven by her thirst for knowledge and her eagerness to continuously expand her horizons. When she is not coding, she is writing articles, studying, teaching or contributing to open source projects here and there.


Install GitLab on your own server in 2 minutes

Browse all posts

For the latest and most detailed news follow @gitlab on Twitter. Future blog posts suggestions.