GitLab is a git-repository manager with some differences to GitHub, although the recent GitHub announcements bring the two more in line with one another.
If you’re not aware of GitLab pages, they allow you to publish static websites directly from a repository in GitLab. There are some limitations, mainly that Pages do not support server-side languages such as PHP, but I mainly use them to host static HTML staging sites. Once set-up correctly pages are generated when the codebase is pushed onto the server and pages can be specific to a branch, for example I use the staging branch to generate the page.
Setting up a GitLab page is a relatively straightforward process. I’ll walk you through the process of setting up a standard HTML config and point out where I got stuck when first setting this up.
- As mentioned above, the repo must not use server-side languages. See here for a complete list of supported languages with example config files.
- A working repo with at least an index.html file.
The .gitlab-ci.yml file
This is the config file that will deploy the codebase to GitLab pages once pushed to the server, the below mostly consists of the html template GitLab generates and the only change I’ve made is to limit this to the staging branch of the project.
pages: stage: deploy script: - mkdir .public - cp -r * .public - mv .public public artifacts: paths: - public only: - staging
Creating a .gitlab-ci.yml file
- To generate this file for yourself, go to your repository and add a new file to the repo by clicking on the
- At the top of the next page you can select a template from the
choose typedropdown, select
.gitlab-ci.ymlthen click the
Apply a GitLab CI Yaml templatebutton and select the project type you’re working on. For this example we’ll choose
- A file very similar to the above should then be generated — you’ll notice the only difference is the
stagingbranch I use.
- Commit the file to your repo, then navigate to
CI/CDon the left navigation and you should see the pipeline is running.
- Once this has completed you should see the
Pagesoption as appeared in the
Settingsmenu on the left side. Inside here you should see a message which states
Congratulations! your pages are served under:and a link to your page.
- You’re done!
Some things to be aware of
You can copy your
.gitlab-ci.yml file to other projects, as long as you call your branch the same name it should work just fine.
If you Group your projects, GitLab Pages can only be generated from repos in the top level of a group, I got stuck trying to generate Pages from a subgroup and this is not supported.
Once you see the
Congratulations! message it may take a short while for the propagation to take place before you actually see your page. Before then you’ll be served with a 404 page, that’s perfectly normal and you’ve done nothing wrong.