After setting up the Hugo site locally the next step is to push it up to GitLab for hosting. For this to work we will:

Setup GitHub project

In your GitLab space (https://gitlab.com/users/<username>/projects) you want to create a new project. In the top right corner you should see a plus icon, to create new project/repository.

You are given some options to create a new project from a template, import from another source (i.e. GitHub) or create a blank project.

One of the templates is for Pages/Hugo. We will not be using this as we have already created the Hugo project in our website creation step. Also, I’ve had problems with the template projects.

Start by creating a new blank project. There are limited options that we need to provide. A project name, and the project URL that will be used. This URL consists of the username or group, you can delect this from a dropdown, and the project slug, which defaults to match the project name.

There is an optional project deployment and we are going to select GitLab Pages here.

Push Site

Once you have created the new project, there will be a default README.md file, which gives some instructions as to how you can use your project. At the bottom of the README.md there is a section, Push an existing Git repository. This explains how to set GitLab as the origin and push your application up.

CI/CD Pipeline

Once the project has been uploaded to GitLab we need a build pipeline to create the HTML site and copy it to the /public directory where GitLab will be serve the site from.

Create the .gitlab-ci.yml file and add the following text into it.

image: debian:bookworm-slim

variables:
  GIT_SUBMODULE_STRATEGY: recursive
  HUGO_VERSION: "0.167.0"

default:
  before_script:
    - apt-get update -qq && apt-get install -y -qq curl
    - curl -sSL "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" | tar -xz -C /usr/local/bin
    - hugo version

# Use everywhere except on the default branch
test:
  script:
    - hugo --minify
  rules:
    - if: $CI_COMMIT_REF_NAME != $CI_DEFAULT_BRANCH

# Run only on the default branch
create-pages:
  stage: deploy
  script:
    - hugo --minify
  pages: true
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
  artifacts:
    paths:
      - public

Once this has been setup on GitLab you can go into the visualise view of your pipeline (https://gitlab.com/<username>/<project>/-/ci/editor?tab=1) where you will see two tasks, test the Hugo build and deploy.

Open access to site

Once the CI/CD build pipeline completes your site will be pushed to a public GitLab server, under a unique domain, something like https://<project>-<hash>.gitlab.io/. There is an option, which I prefer that allows you to run the site from a URL which is structured as, https://<username>.gitlab.io/<project>/. To use this format you will need to go to navigate through the menu on the left to Deploy > Pages, then at the top of the page switch from Overview to Domain & settings. On this screen you should see an option Use unique domain in the settings area, uncheck this box.

On this page, we also have a domains section. We will come back to this when we are setting up the custom domain name.