Background
My Github Pro subscription expired a few days ago, which means although I can have private repo for my blog, it cannot publish new updates any more. Two choices for you from Github: either pay for Pro or change the repo to a public one.
I am happy to contribute to open source world. However, the repo contains some sensitive information, like Google analytics ID, or perhaps some passwords pushed by mistake in commit history.. Therefore I decided to find a free alternative instead of going along with Github.
Happy to find Gitlab Pages, which I think is a perfect replacement of Github Pages, or even better. However, there are still some caveats during migration. Here I will make a summary of this effort. Note that entire migration took me around 2 hours.
Where to push my code?
Gitlab provides an amazing CI/CD feature, which does CI/CD from external repo. So all you have to do is to create a new project in Gitlab by setting up the CI/CD from your Github repo. In this way, you don’t even have to change your local git settings like adding a new origin for Gitlab. But you can do it anyway.
Depending on what you choose, you can either push to Github or Gitlab. Both repos can be private.
How to generate static pages?
Github does this step automatically once receiving a new push. Gitlab needs some configurations for CI/CD (changes -> pages, not Github repo -> Gitlab), but this doesn’t mean it’s not as good as Github. Actually, I was surprised by this feature. It’s much more configurable and thus powerful.
For the example of Pages, add a new .gitlab-ci.yml
file under the root directory with following configs. You can learn more about the config settings here.
image: ruby:2.3
before_script:
- export LC_ALL="C.UTF-8"
- export LANG="en_US.UTF-8"
- export LANGUAGE="en_US.UTF-8"
pages:
stage: deploy
script:
- bundle install
- bundle exec jekyll build -d public
artifacts:
paths:
- public
only:
- master
Push the changes. In order to trigger the page generation pipeline, you need to manually run one in the project’s Pipelines page. The following changes will be generated automatically. You can even view the progress or download the generated html files.
Wait, what’s the url?
The default url will be YOUR_USERNAME.gitlab.io/YOUR_PROJECT_NAME
, which may cause trouble if you didn’t have correct prefix for your assets’ url (css, pictures, etc). I recommend to do following in Project setting -> Advanced. It enables us to use custom domain easily. Without this, the homepage url with custom domain is yourcustom.domain/YOUT_PROJECT_NAME
.
- Rename your project to
YOUR_USERNAME.gitlab.io
- Update its path to https://gitlab.com/YOUR_USERNAME/
YOUR_USERNAME.gitlab.io
After this, the url will be YOUR_USERNAME.gitlab.io
. Custom domain will work as well.
With this setting, url prefix for all your assets in your project should be ""
in your _config.yml
. Otherwise, it has to be /YOUR_PROJECT_NAME
. An example of asset path suffix could be /assets/web/web_design_workflow.png
.
Custom domain is fancy
Easy to set up custom domain with HTTPS. Just follow instruction in Setting -> Pages. Server IP address is provided here. HTTPS support is built-in or you can use your own certificate.
Other caveats
- You shouldn’t name one of your top level directories to
public
. This is a reserved name by Gitlab Page.