Moving from GitHub Pages to GitLab Pages - lmmx/devnotes GitHub Wiki

It doesn't seem possible to enable the greyed out "enforce HTTPS" option for a custom domain where the apex domain and a subdomain are separate GitHub Pages static sites, as GitHub's certbot will only issue a single SSL certificate to the apex domain, and there is no way to add a manually generated LetsEncrypt SSL certificate for such a site.

It's been documented for the more trivial case of wanting SSL certificates to cover the www subdomain, in a long thread dating back 2 years on the GitHub Community support forum.

It is mentioned towards the end of this thread that GitLab Pages can be used instead of GitHub Pages, and will even mirror a site directly from GitHub, and this seems a reasonable fix.

  • To import repos from GitHub, use the interface here
    • GitHub repos are slugged as username-github-io whereas GitLab repos are username.gitlab.io (nice!)
    • Ensure to rename both the repo name and the path (under Settings on the left hand sidebar > General > Advanced)
  • To make new organisations ("if you organise your projects under a group, it works like a folder"), click the plus sign in the top right (to the left of the search bar) or click here
    • You can even make subgroups!

To add a custom domain with SSL certificate, you'll need to add TXT records in your domain provider's DNS management interface, and then run

host -t TXT _gitlab-pages-verification-code.YOURDOMAIN.COM 8.8.8.8

(the 8.8.8.8 uses Google's nameserver to ensure fast lookup) or if it's a subdomain of the apex domain you're setting up,

host -t TXT _gitlab-pages-verification-code.SUBDOMAIN.YOURDOMAIN.COM 8.8.8.8

The output will look like:

host -t TXT _gitlab-pages-verification-code.SUBDOMAIN.YOURDOMAIN.COM 8.8.8.8
Using domain server:
Name: 8.8.8.8
Address: 8.8.8.8#53
Aliases:

_gitlab-pages-verification-code.SUBDOMAIN.YOURDOMAIN.COM descriptive text "gitlab-pages-verification-code=0abc1def2345xxxxxxxx6789yz"

and as soon as you get that rather than a "host not found" message, that means the DNS record (the TXT) you added has 'propagated', and then you can click the little red verification button, which will refresh the page and turn green to say 'Verified' and a banner at the top to say "Successfully verified domain ownership" (at which point the TXT record can be deleted from your DNS manager).

Lastly, if you chose to make your repo private, go to https://gitlab.com/USER_OR_GROUP/USER_OR_GROUP.gitlab.io/edit#js-shared-permissions (Settings > General > Visiblity) and scroll to the end of the settings, where you can change the Pages visibility from Only Project Members to Everyone, i.e. make your GitLab Pages site public (otherwise anyone else will be redirected to the GitLab sign-on page).

  • The domain page may fail to generate the SSL certificate, in which case just click the button to retry, and if the DNS records were configured as instructed it should succeed.
  • The advice to set a CNAME record on your DNS provider can be ignored if you are setting this from the static site repo itself.