Learn More

What is GitLab Pages?


Self-Host for Free

Use GitLab Pages to host your site on the GitLab.com

Use Pre-made Templates

Use any static website generator: Jekyll, Middleman, Hexo, Hugo, Pelican, and more

Create Custom Sites

Create websites for your GitLab projects, groups, or user account

GitLab Pages: Plain HTML How To

In this how-to we will teach you how to make your first use case of GitLab Pages with a plain html example - similar to how this page was created. The uses of GitLab Pages are much farther reaching than what will be covered here. If you're looking for examples of projects, see below.

DISCLAIMER: This tutorial assumes you have an SSH key setup on your machine and you understand how to use Git with GitLab.

Create a Project

  1. Sign in to your profile
  2. Create a project with an awesome name
  3. Save your awesome project

If you need more concise help to accomplish this step, check out this article.

Make a basic HTML Site

This step can be completed by just making a quick HTML outline.

  1. Create a folder on your computer and put a directory in it named public.
  2. Download HTML outline here. Or make your own.
  3. Save the HTML outline and put it in your localfolder/public directory.
  4. If you decide you want CSS - make sure to put all contents in your public directory.

You can also use a static site generator that utilizes a prebuilt framework in the language of your choice.

Your YAML file is what designates your build cycles and your environments as well.

With many SSGs you can find a premade .yml file that you may have to alter slightly based on if you're using an environment like docker and the order you'd like it built through your environments.

The example that GitLab uses in their YAML documentation touches on a Ruby SSG, called Jekyll. For the example here, the .yml file will look similar but will use the lightweight Alpine Linux image to build. You may also notice that this how-to doesn't cover shared/specific runners. That is because there are a few shared runners already setup and your build will automatically use of them; however, you're more than welcome to make a specific runner to utilize for your project alone.

Feel free to download the .yml file from the example repo here, or follow the instruction below.

  1. Create a file name ".gitlab-ci.yml" and save it to the root of your localfolder
  2. Start by listing the image type you're using, in this case you want the latest version of alpine: image: alpine:latest
  3. You can designate your runner to build from any branch, but in this example you'll want only pushes to the default branch (master) to be deployed to your website. To do that, we need to add another few lines to our .yml file, telling the Runner to only perform that job called pages (everything in the public directory) on the master branch only - resulting in this:
  4. That's all you need to get started! If you're building a more complex example take a look at this article that lists all of the build variables. These variables have already gone through some changes, so it's good to bookmark. ;)

Now that we have everything composed, we're ready to push all of the assets we have to our GitLab project.

As soon as you follow the sets below to push everything at once you'll also be automagically pushing your code through the pipeline and having it built by an already configured shared runner.

The following steps will outline how to push an existing project. If you know how to do this, feel free to skip. :)

  1. cd existing_folder
  2. git init
  3. git remote add origin git@gitlab.com:USERNAME/NAME_OF_REPO.git
  4. git add .
  5. git commit
  6. git push -u origin master

If you got an error while pushing, you either don't have an SSH key or personal access token setup correctly. If you know your SSH key is setup correctly and this failed, it is likely you have denoted your remote as an HTTPS address instead of SSH. Learn how to change your remote address here.

Now, if you visit your project on gitlab.com you can see if your build ran corrected by the pipeline status noting "passed" above your files in the project view.

Now comes the fun part! Let's see what our page looks like.

You can visit your pages site by navigating to: https://USERNAME.pages.gitlab.com/NAME_OF_YOUR_PROJECT or by following the directions below.

  1. Navigate to your projects settings.
  2. Select Pages from the submenu.
  3. Click on the link to your page, located in the middle of the screen.