/ #hugo #github 

Hugo meets Github

A while ago…

…I migrated my server infrastructure from a rancher/k8s based setup to a more simple approach (plain docker with a lot of bash scripts & git, I’ll talk about it in another post soon). When it came to migrate the blog itself, I even got rid of the need for the server completely. How?

Github actions ftw

Github launched actions a while ago. I thought “yeah cool”, registered for the beta, but never had time to actually do something with it. Until now.

But what is github actions? It allows you to write scripts which then get executed in certain conditions. Something similar to Travis CI, Circle CI or others. They all come with different pros and cons, mostly it doesn’t matter which one you choose. However - when your code is hosted on github - i feel it a bit more “natural” to work with github actions - as i have to switch less between pages.

Okay but this article is about deploying hugo, so how can github actions help with that?

Hugo needs a compile step to create the html files out of the md files. Usually I don’t like having files that can be generated in my repository, so I only store the .md files there. When deploying it somewhere, the html files need to be created first.

So we can run an actino creating the html files whenever something gets merged to master. Cool? Cool! But where to put them?

Github pages

While we could push the files to a server with something like rsync or scp, why not use github for this as well? Github is an excellent hoster for static files. There are some limits, but for something like a small blog you won’t ever reach it.

How does it work? Github-Pages can be activated on any repository and then will host everything that’s contained within the special branch “gh-pages”. By default the domain name is something like http(s)://<username>.github.io/<repository>, but it’s also possible to use your own domain for it, including ssl.

Build & deploy

Here’s the actual script on how I’m currently doing it. Put it in your repository under <root>/.github/workflows directory and afterwards every merge to master automatically gets deployed to gh pages. No server needed, github does everything.

name: deploy to github pages

      - master # Set a branch to deploy

    runs-on: ubuntu-18.04
      - uses: actions/checkout@v2
          submodules: true # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
          hugo-version: "latest"

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          cname: blog.jbrosi.dev

You don’t want this to happen on every master merge but when manually drafting “releases” in github? Sure, we can do that as well. Just replace the “on build” part in above script with the following:

    types: [created]


Passionate coder; discovered the black magic of writing programs in the age of 13 and still loving it. When not fighting with bits & bytes probably seen outside with a camera.