As GitHub and Export Controls said GitHub.com, GitHub Enterprise Server, and the information you upload to either product may be subject to US export control laws, including U.S. Export Administration Regulations (the EAR)., I decide to migrate my personal hugo static blog from GitHub to GitLab.

More important, GitLab Pages is simpler and faster than GitHub Pages.

Old blog is Using Hugo and Travis CI To Deploy Blog To Github Pages Automatically.

Official Documentations

Official documentation page is GitLab Pages.

Setting procedures

  1. Static sites and GitLab Pages domains
  2. Projects for GitLab Pages and URL structure
  3. GitLab Pages custom domains and SSL/TLS Certificates
  4. Creating and Tweaking GitLab CI/CD for GitLab Pages

GitLab CI/CD Pipeline

Operation Roadmap

  1. GitLab create group, import project from GitHub;
  2. Change default branch, unprotect protected branch;
    • Delete default master branch, rename branch code to master, change default branch to master
  3. Create file .gitlab-ci.yml;
  4. CloudFlare
    • DNS setting;
    • SSL certificate generating;
  5. Add custom domain in GitHub Pages;
  6. Slack notification

Because I set this project as private project in GitLab, images will not be allowed to visit in web browser. So I decide to use GitHub only as image project.

If you wanna use image url from GitLab directly, you can set your project as public project.

Migrating Project

GitLab supports import project from GitHub, but it needs access token generated from GitHub. So you need to generate a personal access token from GitHub (Settings –> Developer settings –> Personal access tokens –> Generate new token) first.

GitLab Group

According to GitLab Pages domain names, create new group axdlog, project name axdlog.gitlab.io, the pages url will be axdlog.gitlab.io.

GitLab home page

Sign in page ![](https://gitlab.com/axdlog/axdlog.gitlab.io/raw/image/blog-image/2019-05-24-GitLab-Pages/2019-05-24_13:59:34_Sign in.png)

Two Factor Authentication

After sign in

New group button

Add new group

New group page

New Project

GitLab provides 4 methods to create project.

Method 1 - Blank project

Method 2 - Create from template

Method 3 - Import project

Method 4 - CI/CD for external repo

Import project

Here choose method 3 Import project.

Generating personal access token from GitHub.

Pasting token

Import process

Change path to axdlog/axdlog.gitlab.io.

Scheduled status

Success status

Project Overview

Now you can browser you project in GitLab web page.

SSH url

Branch Operation

GitLab protect default branch by default, you need to change default branch, unprotect protected branch first. Or it will prompt errors

remote: GitLab: You can only delete protected branches using the web interface.

Web Page: Settings –> Repository –> Protected Branches –> Protected branch –> Unprotect

remote: GitLab: The default branch of a project cannot be deleted.

Web Page: Settings –> Repository –> Default Branch

Delete default master branch, rename branch code to master, change default branch to master

Default Branch

Protected branch

Change Default Branch

Cli Command

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# list all branches local and remote
git branch -a

# remove existed master branch
git push origin --delete master

# rename local branch from 'code' to 'master'
git branch -m code master    

# push the new branch, set local branch to track the new remote branch
git push --set-upstream origin master

# change default branch (remotes/origin/HEAD) to branch master
git remote set-head origin master

# delete the old branch 'code'
git push origin --delete code

Operation records

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
$git clone [email protected]:axdlog/axdlog.gitlab.io.git
Cloning into 'axdlog.gitlab.io'...
remote: Enumerating objects: 17349, done.
remote: Total 17349 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (17349/17349), 40.34 MiB | 10.82 MiB/s, done.
Resolving deltas: 100% (9151/9151), done.

$cd axdlog.gitlab.io/

$git branch -a
* code
  remotes/origin/HEAD -> origin/code
  remotes/origin/code
  remotes/origin/image
  remotes/origin/master

$git push origin --delete master
To gitlab.com:axdlog/axdlog.gitlab.io.git
 - [deleted]           master

$git branch -m code master

$git branch -a
* master
  remotes/origin/HEAD -> origin/code
  remotes/origin/code
  remotes/origin/image

$git push --set-upstream origin master
Total 0 (delta 0), reused 0 (delta 0)
remote:
remote: To create a merge request for master, visit:
remote:   https://gitlab.com/axdlog/axdlog.gitlab.io/merge_requests/new?merge_request%5Bsource_branch%5D=master
remote:
To gitlab.com:axdlog/axdlog.gitlab.io.git
 * [new branch]        master -> master
Branch 'master' set up to track remote branch 'master' from 'origin'.

$git remote set-head origin master

$git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/code
  remotes/origin/image
  remotes/origin/master

$git push origin --delete code
To gitlab.com:axdlog/axdlog.gitlab.io.git
 - [deleted]           code

$git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/image
  remotes/origin/master

.gitlab-ci.yml

GitLab CI/CD is triggered by file .gitlab-ci.yml in the root directory of project, create this file, then change variable baseURL to https://axdlog.gitlab.io in file config.toml.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# All available Hugo versions are listed here: https://gitlab.com/pages/hugo/container_registry
# https://gitlab.com/pages/hugo/blob/registry/Dockerfile
image: registry.gitlab.com/pages/hugo:latest

variables:
  GIT_SUBMODULE_STRATEGY: recursive

stages:
  - test
  - deploy

# before_script:

test:
  stage: test
  script:
  - hugo
  except:
  - master

pages:
  stage: deploy
  script:
  - hugo
  artifacts:
    paths:
    - public
  only:
  - master

Commit info

Pipelines

Stages

status running

status passed

deploy stages

Job detail

Artifacts

In GitLab CI/CD, artifacts is used to specify a list of files and directories which should be attached to the job after success.

Hugo generate html file in directory public, GitLab Pages save them in to Artifacts. You can browse or download it.

GitLab Pages

Switching to pages page (Settings –> Pages), you can see the default access pages url.

Browsering this url, it may appear 404 page, just wait minutes then reload page.

It works

CloudFlare

Using SSL certificate provided by CloudFlare.

Site Overview

CloudFlare homepage

Sign in page

Dashboard

Add Site

You can set CNAME records latter.

Change your nameservers in your domain register.

DNS Page

DNS CNAME records

type key value
CNAME axdlog.com axdlog.gitlab.io
CNAME www axdlog.com

Add CNAME records

Origin Certificates

Creating SSL certificate, more details in Issuing Certificates

Here choose RSA, GitLab doesn't support ECC.

New Pages Domain

Pasting certificate and private key generated from CloudFlare. GitLab Pages needs to upload the Cloudflare Origin CA root certificate. Just paste cloudflare_origin_rsa.pem below your certificate (PEM).

More details in

According to DNS TXT record, you need to create a TXT record containing a verification code to prove that you own the domain. The code will be displayed after you add your custom domain to GitLab Pages settings.

Custom Domain Verification

Adding verification code to DNS TXT record to verify ownership.

type key value
TXT *_gitlab-pages-verification-code.axdlog.com* gitlab-pages-verification-code=0efdcc54eab467eafba72ae24fc85bea

verifing success

Pages overview, now it has custom domain axdlog.com.

Testing

The web browser fails to load css file, you need to change bashURL to axdlog.com in file config.toml.

Result

Visiting custom domain in web browser

SSL certificate

Slack Notifications

GitLab supports Slack notification, just following

Setting

Testing

Chnage Log

  • May 24, 2019 19:03 Fri -000 EST
    • first draft