Migration to Gitlabs

Why switch to Gitlab ?

The selling point for me was that while both Github and Gitlab can host static web pages for free, Gitlab also allows the repository for the web page to be private for at no cost. Github only allows using their Github Pages implementation with a private repository if: at minimum, you pay for Github Pro ($7/mo). While I don’t have anything sensitive on my web page, there’s no need to leave the repository out in the open. Gitlab allows the option free of charge, so I opted for moving towards hosting on Gitlab.

Gitlab and Github Pages

I thought setup the process would be basically the same–unfortunately the set up is a bit more involved for Gitlab.

My web page is built on the Hexo Framework (a static web page generator–basically an alternative to more popular Jekyll). Honestly the only justification for why I didn’t use Jekyll is cause I’m a hipster. Hexo works by reading source “.md” or markdown files that contain content formatted with the markdown syntax and utilizes “.ejs” or embedded javascript template files to build out static HTML files combined with CSS files that make the website look nice. The Hexo Framework runs on the Node.js Runtime Environment. For Github, the process for building the web page was using Hexo to generate the static web page files and pushing the files to a repository branch called “gh-pages”. The only quirk I had with Github pages was that since I didn’t use Jekyll, I needed to add a .nojekyll file to the repository (its just an empty file literally named .nojekyll). Other than that, my web site was up and running in a matter of minutes from my initial commit. Setting up the domain was a breeze as well, the only caveat was the need to drop a CNAME file into the repository.

The first oddity I had with Gitlab was that I couldn’t push my repository to Gitlab. It kept hanging. After terminating the attempts and re-trying a few times, it finally went through. Not a great first impression. Nevertheless, this initial push was a fluke anyway since it turns out I couldn’t use the repository structure I had with Github.

For Gitlab, you cannot simply push the generated static web pages to a specific branch on the repository. Instead, you have to push the files you used to generate the static web pages. I had to push up the node_modules, source, themes, scaffolds directories that were created from initializing Hexo in a folder. I then added a .gitignore file in order to prevent GIT from staging the /public/ folder to the repository (the public folder contains the generated static web pages). Gitlab then expects a .gitlab-ci.yml file in the repository.

My .gitlab-ci.yml below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

image: node:11.12.0 # match local version
cache:
  paths:
    - node_modules/

before_script:
  - npm install hexo-cli -g
  - npm install
  - npm rebuild node-sass #I was getting CSS errors unless I rebuilt node-sass

pages:
  stage: deploy
  script:
    - hexo clean
    - hexo generate
  artifacts:
    paths:
      - public
  only:
    - master

Basically this file is used for “Continous Integration (and continuous deployment)” aka CI / CD.
The YML file tells Gitlab how my web page is to be built: Use the Node.Js image 11.12.0 (just happens to be the version installed on my local machine), some paths, the scripts for installing Hexo and some dependencies, the scripts for generating the page and the path to the generated static web page files.

To allow the processing of Node.js and Hexo on Gitlab, I had to go to Settings -> CI/CD -> Enable shared Runners. Per Gitlab these are Google Cloud VMs that power the generation and deployment of the site. Note that everytime I push a commit to the Gitlab repository, the webpage is rebuilt and redeployed. This takes on average 2 minutes and 30 seconds for my page; I imagine it will take longer when the site grows larger. Per Gitlab’s limits, I only have 2000 minutes of CI per a month (this roughly translates to a limit of 800 pushes per a month). This limit seems pretty fair, you can always test the web page locally on your machine before pushing changes to the remote repository.

Setting up a Namecheap Domain

This was the biggest pain point of this whole migration. Gitlab documentation kind of sucks. Okay, that’s unfair to say, how about: Gitlab Documentation covers a lot of ground, but its annoyingly inconsistent at times oddly too specific. When first setting up a custom domain for your webpage, it will require you to perform verification. First you need to click the green “New Domain” button when using the left side Settings menu and navigating to Pages.

Upon clicking the New Domain button you will see a screen shot like the one below. Note that this is pulled directly from Gitlab’s documentation:

Then if you scroll just a wee bit further down you will see the following:

My issue with this is that the documentation appears to be listing steps in sequential order 1, 2, 3..–in other words, you would follow them step by step. However the first screen shot shows that when adding a Domain, the page advises you to add a CNAME record. Then once you scroll down to the DNS records section, the first option is for root domains by adding an A Record. While theoretically both methods work, you shouldn’t need both (aside from some more complicated cases).

My last point that bothered me was that their documentation was oddly geared towards one registar:

Okay. We get it. Cloudflare is cool and I like them too for their DDoS mitigation tools–but I don’t use them. How about some caveats for other popular Domain Registars (like Namecheap?).

Getting the domain to work

First use the settings for the Gitlab Repository and navigate to Pages to create a new domain(like the first screen shot above). One thing you might notice is that each of my records do not quite match what the documentation from Gitlab specifies. It’s frustrating and time consuming because you can’t simply make a change and see if it works. The DNS Records can take time to propagate so you might find yourself chalking it up to “oh the setting hasn’t propagated yet…” when it reality the config doesn’t work.

At minimum to get a domain such as example.com to work, you only need an A record and TXT record for verification purposes:

The @ symbol value simply points to your domain on Namecheap. Notice that I did not append my domain to the host value for the TXT record. Namecheap appears to append it on its own.

Once the DNS settings propagate, you should be able to navigate to your page using your domain name. Domain verification can now be completed (click the refresh symbol next to the red “unverified” text) on the domains page for the Gitlab Repository.

If you get a 401 error (unauthorized), make sure to go to the settings on the left side menu. Go to General and expand the Visibility, project features, permissions section. Scroll down to Pages section and make sure the indication is “everyone”. Note that I had to toggle this on and off to get it to work.

Getting www and non-www domain to work

Now you’re not quite out of the woods yet, what if you want your web page work with both the www and non-www version of your domain? In order to get the www domain to work, you will need to add another domain using the Gitlab Page settings. For the specified new domain, make sure to prefix it with www. Like the previous domain entries: you will need to create an A Record, a TXT record but also a new CNAME record.

Notice that the TXT record appends “.www”

Now your records should look something like:

On a side note, if you are creating a TXT record for Google Search Console, copy the verification code into the Value column and use a Host value of @

Things to do

• Clean up mobile interface: Currently the web page renders nine posts per a page (three wide x three tall). While it makes a nice uniform square on a desktop or laptop, on my phone, it renders the boxes with two columns (one column four posts high and the other five posts high).
• Develop some sort of easy tool to make quick posts. While I enjoy the involvement of managing a fully static web site, adding posts that are formatted nicely is very time consuming
• Migrate pictures to Google Photos: Currently the newer posts are on Google Photos but older posts have pictures hosted directly on the repository (which can be slow to load!)
• Fix any remaining mixed content (should all be on https)