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
If you need more concise help to accomplish this step, check out this article.
This step can be completed by just making a quick HTML outline.
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.
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. :)
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.