GitLab Pages is a static website hosting service.

Hexo is a blog framework that generates static website.

This tutorial explains how to install Hexo, create basic static website and host it on GitLab Pages.

Install prerequisites

Register on GitLab.

Install Git version control system.

Install Node JS. I prefer installation through NVM (Node Version Manager)

Install Hexo Cli

Run this command to install hexo-cli npm package globally

1
npm install -g hexo-cli

Create Website with Hexo

Initialize new Hexo project

1
hexo init <project_name>

Go to new folder and install dependencies

1
npm install

Add pages and posts

Command to create new post

1
hexo new post "post title"

Command to create new page

1
hexo new page "page_name"

Run Hexo server to preview your website and posts

1
hexo server

For more information see Hexo documentation. Also you can use help command instead documentation. Sometimes it could be much faster. Just run hexo help to see all available commands.

Create new GitLab repository

Create new repository on GitLab website. Then initialize new repository in project folder

1
git init

Add your created remote GitLab repository to your local repository

1
git remote add origin <your_repository_link>

Add GitLab Deployment Configuration

Hexo is static website generator. But it doesn’t store generated html files in Git repository. You can generate static files automatically every time you send updates to remote repository with GitLab Continuous Delivery (CD) tool.

Add new file .gitlab-ci.yml to your project with this content

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
image: node:12
cache:
paths:
- node_modules/

before_script:
- npm install hexo-cli -g
- npm install

pages:
script:
- hexo generate
artifacts:
paths:
- public
only:
- master

Config explanations:
image - specify Docker image. Here used official Node JS Docker image
cache:path: - specify folder to cache between jobs
before_script - run this script before jobs
pages - actual job
pages:script - actual script to run. Here we generate static pages with Hexo.
artifacts:paths - this folder will be available in GitLab UI after the job finishes
only - conditions to run jobs, i.e. run this job only on master branch

Reference:
Actual Hexo config
Actual GitLab yaml reference

Commit your project

To save state of you blog, run command

1
2
git add --all
git commit -m "Commit message, describing your changes"

Create Page on GitLab

Go to your GitLab repository and open Settings - Pages. Then create New Domain for this repository.

If you have your custom domain, add TXT record in domain admin panel to verify it and A record to map your domain to GitLab Pages. You can get GitLab Pages IP here.

Then go to Settings -> CI / CD -> Shared Runners and click Expand in Runners. Enable Shared Runners if it disabled.

Make your page available: go to Settings - General, click to Visibility, project features, permissions and change configuration for Pages to Everyone

Upload your website to GitLab

Push your local changes to remote repository with command

1
git push -u origin master

After push GitLab CD automatically generate static files and update your website.
You can see running job in project Settings - Pipelines or Jobs.