This is a short post on how to host multiple Gitlab project pages using a single Gitlab account. This task is actually very simple, but I could not find any documentation on it when I tried a couple weeks ago. I ended up resorting to creating a second Gitlab account. Turns out you do not need to use this hack, and this post will explain how to legitimately host multiple gitlab pages with just one account.
Gitlab User Pages verses Project Pages
As documented in my my initial Gitlab deployment post, the Gitlab Hugo document says to create or rename your project to namespace.gitlab.io, where namespace is your username or groupname. This did not work because I was renaming an existing project that already had a non-root project path (also known as a project slug). As I documented, what really matters in determining your page URL is not your project’s name but your project’s path. Gitlab refers to this type of page (with a namespace.gitlab.io/project url) as a project page verses the namespace.gitlab.io url pages being a user or group page. Great - I can host numerous pages in a single repo, but how do I map custom domains to these unique project pages?
Mapping a Custom Domain to a Project Page
I then tried to map my domain mjkranch.com to archang31.gitlab.io/mjkranch.com, but you can only point CNAME DNS records to domains and not subdirectories of a domain (so I can point it to archang31.gitlab.io but not archang31.gitlab.io/mjkranch.com). Stuck on this issue, I simply changed my project path from /mjkranch.com to just /. That worked great for my first project, but how do I then host a second site?
Turns out, you can use gitlab pages to internally pair GitLab project pages to unique subdomains. The CNAME for all your pages will be the same namespace.gitlab.io, but GitLab will internally handle the redirection to the correct project page based on the referring domain. All you need to do to enable this functionality is add the appropriate domain to your GitLab Project (under settings->pages), configure the appropriate CNAME and TXT records for your domain, and then confirm verification of the GitLab domain. You can add this project as a either a main domain or subdomain of a existing domain. You can also map a project page to a subdomain (like the below example Project Page is mapped to example.mjkranch.com). This will allow you to host many different project pages in one repo through a single domain but can not use a sub-subdomains. This page walks through how to add the GitLab pages (and a cert) with my comments here providing some additional details.
GitLab Pages Conflicts
Warning: The below example is broken now, but the potential conflict still exists; however, it is a very minor thing that only impacts people that directly visit your namespace.gitlab.io site so probably nothing you will ever encounter.
There is a small potential conflict with your internal projects if visited via gitlab.io since you can map a since subdirectory to two different pages. Let me demonstrate.
I created a /example/ directory with a page on my main page, mjkranch.gitlab.io, but I also created an example GitLab project page with the slug /example/. Which page will be served if you go to mjkranch.gitlab.io/example? The answer is the project and not the subpage of the main mjkranch.com page. You can verify this subpage exists by visiting mjkranch.com/example. The take-away is that you can potentially overwrite gitlab.io pages with Project Pages but not when you use your own domain (since its then based off the subdomain).