Migrating My Website to GitLab Pages with a Custom Domain

In the fast-evolving world of software development and digital publishing, having control over your build and deployment pipeline can be transformative. That’s exactly what prompted me to leave behind my traditional hosting provider—and GitHub—and migrate my Hugo website to GitLab Pages. The process was refreshingly smooth, though I did do this over a couple of weekends to be able to test and be sure of everything and the benefits were immediate. It simplified my website development and publishing down to one ’tool’ - Gitlab.

Why the Move?

First, the obvious: cost. GitLab Pages doesn’t charge a cent for public projects. But it was GitLab’s powerful built-in CI/CD tools that sealed the deal. I no longer needed Buddy or any external deployment tool. Everything from build to publish now happens in one place.

The bonus? Simplicity. Hosting, source control, and deployment under one roof reduces complexity and increases focus. GitLab felt like a more integrated, more developer-centric home.

Step 1: Migrate Your Project to GitLab

Transferring my codebase was almost effortless thanks to GitLab’s import wizard. From the GitLab dashboard:

1. Select New Project > Import project > GitHub.
2. Authorise access to your GitHub repositories.
3. Pick the project you want to move.

In minutes, GitLab imported my repo—branches, tags, commit history and all. No command-line gymnastics required.

Step 2: Add .gitlab-ci.yml for Hugo Builds

Next up: automation. I created a .gitlab-ci.yml file to instruct GitLab’s runner to build my Hugo site whenever I push to the main branch.

image: klakegg/hugo:latest

pages:
  script:
    - hugo
  artifacts:
    paths:
      - public
  only:
    - main

This minimalist config uses a Hugo Docker image to generate the site, then saves the result to a public/ folder that GitLab Pages automatically publishes.

Step 3: Enable GitLab Pages

With the CI pipeline in place, GitLab Pages springs to life. Head to Settings > Pages, and there it is: your freshly deployed website, available at https://yourusername.gitlab.io/your-hugo-site.

Step 4: Test the Site

Before setting up a custom domain, it’s critical to make sure everything renders as it should.

1. Update your Hugo config.toml or config.yaml to match your GitLab Pages URL:

   baseURL = "https://yourusername.gitlab.io/your-hugo-site/"
   

2. Commit and push the changes. GitLab CI will rebuild and redeploy the site.

3. Open the site in a browser. Check navigation links, images, stylesheets—everything.

Catch glitches now, before you go public.

Step 5: Set Up Your Custom Domain

Custom domains add polish, and GitLab supports them natively:

1. Go to Settings > Pages > Domains.
2. Add your desired domain.
3. Follow the DNS instructions provided—typically a CNAME or A record.

Bonus: GitLab can issue HTTPS certificates automatically via Let’s Encrypt, making your site secure with zero fuss.

Step 6: Verify Everything Works

Run through a final checklist:

• The CI/CD pipeline completes without error.
• The site loads correctly on both the GitLab URL and your custom domain.
• DNS has propagated globally (tools like whatsmydns.net are helpful).

Optional: Tidy Up the Past

Once your project lives fully on GitLab, don’t forget to clean house. Update your README, update backlinks, and if you’re sure you’re done with GitHub, consider archiving or removing the old repo to avoid confusion.

Final Thoughts

In an era where developers are juggling tools, providers, and workflows, GitLab offers a refreshing consolidation. The ability to manage source, pipelines, and deployment from one interface is not just convenient—it’s empowering.

For me, replacing a paid host and a third-party CI tool with one integrated platform was a no-brainer. If you’re running a static site like mine and want more control without the complexity, GitLab Pages is well worth a look.

Meet the author

Damien Saunders
An experienced management consultant and business leader interested in digital transformation, product centred design and scaled agile. If I'm not writing about living with UCTD (an autoimmune disease), I'm probably listening to music, reading a book or learning more about wine.
Find our more about me.