[solved] Finding a basic workflow with Hugo and Gitlab-pages



I`m new to Hugo and Hugo seems to provide a way better approach to one of my projects on Gitalab-pages.

I`ve tried maaaaany diferent ways to get this working:

  1. Following the Quickstart guide with many different small changes.
  2. Following many tutorials found around the web.
  3. As well as trying to adapt some Hugo+Github-pages tutorials to the Gitlab context.
  4. Also trying to work with a forked Hugo-repository

In all of those, I succeded to create a site, content and change the theme locally. Once the site was working locally, I would try a similar approach to @appernetic (added the '.gitlab-ci.yml) and pushed.

The closest I could get, was adapting this tutorial that I found here on the forum (thanks @mantzas!) .

I also got pretty close with the forked Hugo repository provided by Gitlab-pages.
But in both situations I fail to understand Hugo`s basic behaviors:

  • The site - if I understand - is actually just the public/ forlder. The forked Hugo-repository appearently consists of only the public/ folder, (right?!), which means I cannot run $hugo since it generates forlders and files that should be outside (../).
  • When following any of the tutorials, if I run some kind of $ hugo command (ex: $ hugo --theme=sometheme), Hugo creates a public/ folder, but it doesn’t create a .gitlab-ci.yml neither a config.toml, so it cannot build after being pushed. When I manually copy and paste these files inside the public/ directory it:
  • “works” but without any layout (no css) or
  • it just says it couldn’t find themes/ (despite the fact that it was not in the .gitignore anymore for testing purposes).

I have the feeling that I could have used the forked repository (or any of the methods I’ve seen around) if I don’t run $ hugo. I also have the feeling that I’m missing something by not properly understanding $ hugo -d.
Should I fork it, then install Hugo on the parent directory?
Or maybe, if following the Quickstart guide, should I $ git init only inside the public/? If so, does public/ really need to be deleted before commiting just because of $ hugo new post/*.md?
It doesn’t seems right to never use any kind $hugo:wink:

Considering what I’ve seen, it would be great to have a /dev/ repository (with everythin, but not as a page), and /public/ repository (with just the /public/ - and the .gitlab-ci.yml and conf.toml). Maybe in instead of two repositories, just two branches to merge around. Or even better, just one branch that succeds build the site contined inside public/.

By the way, using Hugo v0.16 on Archlinux overhere.

Somehow I couldn’t go any further. Most probably because of lack of knowledge around Hugo (and git!).
I’ve been through the whole documentation a couple of times, and I 've been
visting this forum the whole week. So, I don’t wanna give up, and I
would love to hear what am I missing here.

And if the documentation team needs to know how a dummy reacts to the docs, just let me know.
Thank you for your patience!



On GitLab you need to push the whole Hugo project to your repo, then GitLab creates the site for you if you have the right .gitlab-ci.yml file included and .gitlab-ci.yml should be in the root of your repo.

To have a theme working, you clone it and place it in the themes folder, then use the config.toml file from the example folder or create a new one with the authors suggested config settings, and with the name of the theme. Theme to use (located in /themes/THEMENAME/). So if the theme has the name hugo-test-theme add theme = “hugo-test-theme” to the config file. Then push the whole project to GitLab and it should be working.


Thanks for taking the time, @appernetic! You really helped me understand it better.
But, all the problems disappeared once I started downloading and copy+pasting the themes, in instead of clonning them.

When downloaded they don’t bring the .git folder from github…

And thanks for pointing the right .gitlab-ci.yml, that’s also something I should have paid more attention to. (:slightly_smiling:


This answer helped me to fully continue with the process, I deleted all the git files and pushed again and worked perfectly, that should be a commented in some point of the tutorials… Thank you very much @lsrdg


That’s great @whgandalf.

I deleted all the git files and pushed again and worked perfectly

That seems to be even easier :wink:


You shouldn’t need to do that.

When the Gitlab CI runner runs, it only clones your blog git repo. It will not clone nested git submodules like a theme git repo unless you ask it to.

I prefer to not blend my theme and blog repos. That way I can independently maintain my theme and reuse it in multiple blogs.

Here is my Gitlab CI config: https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io/blob/master/.gitlab-ci.yml

Here is the relevant piece from that that clones the theme:

  # * Install my theme; need to first install git and then do git submodule update for that.
  - apk add git
  - git submodule init
  - git submodule update --force

You also need a .gitmodules that points to the sub-modules: https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io/blob/master/.gitmodules


@kaushalmodi I tried what you mentioned but I am afraid something is not good in your file and it is not finishing the job, here is the error:

$ tar xf hugo_DEV-Linux-64bit.tar.gz && cp hugo /usr/bin/hugo tar: can't open 'hugo_DEV-Linux-64bit.tar.gz': No such file or directory $ hugo version /bin/sh: eval: line 56: hugo: not found ERROR: Build failed: exit code 127

I understand cannot find a file to untar but where that file should be ?


@whgandalf I didn’t expect that entire file to be used by someone else :slight_smile:

For that to work for you, you also need to put this in your blog repo: https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io/blob/master/hugo_DEV-Linux-64bit.tar.gz

I build that myself using the master branch. So it is version 0.18-DEV at the moment.


@kaushalmodi I tried to do it as you mentioned and didnt worked at the first try, by the way I understood what you wanted to do in your .gitlab-ci.yml and I try again like 8 times until I got it working.

here is my working version for who can need it:

`image: alpine:3.4

  • apk update && apk add openssl
  • wget https://github.com/spf13/hugo/releases/download/v0.18.1/hugo_0.18.1_Linux-64bit.tar.gz
  • tar xf hugo_0.18.1_Linux-64bit.tar.gz && cp ./hugo_0.18.1_linux_amd64/hugo_0.18.1_linux_amd64 /usr/bin/hugo
  • hugo version
  • apk add python
  • apk add py-pip
  • pip install --upgrade pip
  • pip install Pygments
  • pygmentize -V
  • apk add git
  • git submodule init
  • git submodule update --force
  • hugo
  • master
  • hugo
    • public
  • master`

Lets continue HUGOing


Shouldn’t the tutorial Hosting on Gitlab contain a clause about changing the baseURL setting from example.org when a new site is bootstrapped with hugo new site site1 command ?