Of the multitude of hosting options, Gitlab Pages offers a great free option for developers to run small static sites and testing environments. Given the great number of configuration options, it can be difficult to find a succinct quickstart for Gitlab pages that actually gets you rapidly up and running. The linking of a custom domain name can furthermore be particularly troublesome, as Gitlab’s instructions may not work for your registrar. Therefore the following instructions are provided to get your static site up on Gitlab Pages using Jekyll (static site generator) and Namecheap as a domain name registrar. I’ve had similar success using React and Hugo (with tweaks to the continuous integration yml file).

General overview:

• create a new empty gitlab repository
• populate the new repository with a new Jekyll site
• create a simple .gitlab-ci.yml file that publishes your Jekyll site whenever a commit is made to Gitlab
• link your custom namecheap domain to the website

initial gitlab setup

• create new empty repo (w/o readme)
• set pages visibility to everyone via settings -> general -> visibility -> pages -> everyone -> save

setup simple static site - here using Jekyll

• install jekyll
  • for ubuntu see https://jekyllrb.com/docs/installation/ubuntu/
  • another installation guide: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-jekyll-development-site-on-ubuntu-20-04
• create new local project: jekyll new jekylltest
• test default creation: cd into folder and activate webserver via jekyll serve & click terminal link at default address/port -> this should render the default Jekyll site

link local jekyll directory to a gitlab repository

• initialize the local jekyll directory as a git repository: git init
• rename default branch from default “master” to gitlab’s default of “main”: git branch -m main
• add the initial files to a commit: git add .; git commit -m "init commit"
• ensure you have your gitlab account linked to your local machine for ssh access: https://docs.gitlab.com/ee/user/ssh.html
• copy the “clone ssh” link for the empty gitlab repository you created above
• link your new local directory to the new blank repo: git remote add origin <copied gitlab ssh clone link>
• push local folder to gitlab: git push -u origin master

configure jekyll website via ci.yml file

• add .gitlab-ci.yml with the following content to root directory of your local repo:

image: ruby:latest

variables:
  JEKYLL_ENV: production

pages:
  script:
  - bundle install
  - bundle exec jekyll build -d public
  artifacts:
    paths:
    - public
  only:
  - main

• push this change to gitlab: git add .; git commit -m "add gitlab pages ci.yml"; git push origin main
• go to web gitlab repo -> CI/CD -> jobs and monitor progress of processing yml file
• if not errors with yml file, then verify page working on gitlab.io
  • to see site address go to settings -> pages. note there is a delay from execution of yml script to refresh of this gitlab pages page

configure namecheap domain name for gitlab pages page

• on gitlab pages page -> “new domain” on top right

• enter in domain - I prefer www subdomain (i.e. www.DOMAIN.com) -> hit create

• do not follow gitlab’s instructions as they generally do not work to link the domain, instead do the following on namecheap for entries under DNS -> advanced:

  • remove the default namecheap CNAME www parking redirect
  • leave default URL Redirect from @ to www.<YOURDOMAIN>.com
  • add A record with host www.<YOURDOMAIN>.com to target gitlab ip 35.185.44.232
  • add ALIAS with host www to target your gitlab subdomain page - e.g. <YOUR_GITLAB_USERNAME>.gitlab.io
  • add TXT record with host _gitlab-pages-verification-code.www to target of gitlab-pages-verification-code=<YOUR_SPECIFIC_GITLAB_CODE>
  • the gitlab code can be found after “…code=” in the long string on the gitlab pages page

• notes on time to changes:

  • I’ve set the TTL values to 1min to try and expedite the verification process through gitlab
  • it can still take a while for the settings to percolate from namecheap to gitlab - just keep hitting the “retry verification” button on the gitlab pages page
  • an https/SSL cert can be automatically generated via Gitlab’s integration with Let’s Encrypt, but this can similarly take a while to become activated - just keep checking back to the gitlab pages page until the “Gitlab is obtaining a “Let’s Encrypt SSL certificate” in the bottom blue box goes away
  • after the SSL cert is obtained you may still get transitory errors such as “SSL_ERROR_BAD_CERT_DOMAIN” until the change more fully gone through the net

• once the above changes have percolated through DNS/gitlab, you should have your site accessible via your domain name with SSL

• domain refs:

  • gitlab instructions: https://docs.gitlab.com/ee/user/project/pages/custom_domains_ssl_tls_certification/index.html#adding-an-ssltls-certificate-to-pages
  • namecheap recommendations: https://www.namecheap.com/support/knowledgebase/article.aspx/10446/2208/how-do-i-link-my-domain-to-gitlab-pages/