Moving to GitHub Pages

Hosting Hugo on GitHub Pages

As mentioned in my last blog post my goal was to move this entire homepage to be hosted on github pages.

TL;DR: My ToDo

• create blog locally
• add content
• setup github pages
• add github action to auto deploy
• update DNS zone

Hugo Build

The straight forward thing to turn this collection of Markdown and other resources into a proper webpage is to simply have Hugo built it. The command to achieve this is:  hugo --minify. This will spit out a directory ready to be served by your trusty old  httpd of your choice.

Setting up GitHub Pages

So the next thing was to identify how to tell  GitHub that I some static stuff hosted and no, it’s not Jekyll. It turns out there are three ways to (trust me I’ve used them all):

Of course people with better reading skills would have figured that out from the GitHub Pages documentation already.

That’s not all there is to do here. One actually needs to tell GitHub which  branch to use. This is easy to locate in the actual repository settings.

Now we only need to create that branch and push it to GitHub and the page should appear. Quick question for Git pros, how do you creata a new empty branch that doesn’t have any ancestors when you already populated your main branch (for example if somebody comitted the source files for this blog already)? Turns out that thing is called an orphan branch. This is how it can be done locally for a new branch called gh-pages:

git checkout --orphan gh-pages
git reset --hard
git commit --allow-empty -m "Initializing gh-pages branch"
git push upstream gh-pages
git checkout main

This worked liked a charm initally but one problem I faced was with the Hugo baseUrl configuration. Locally in development mode everything lives on the root context so naturally this is how I crafted my urls in configs and css. But this is not portable to a deployment under a subcontext (first repository naming option mentioned above). It seems like Hugo is smart enough to detect that the base url changed to something containing a path but this smartness doesn’t apply automatically in all instances. I also suspect that the theme I’m using may have problems with this kind of setup. So in the end only the last option (hosting on the root context) does really work sufficiently.

Deploy on Push with GitHub Actions

GitHub Actions is a really neat newish feature of GitHub. It comes with a marketplace and it didn’t take me long to identify working recipe to apply to my repository. So one basically creates a YAML  file through the provided UI and that’s all that is needed to run actions on pushes. Actions even provides the necessary security tokens etc. behind the covers to enable creating new Git commits automatically.

Mine at the time of writing looks like this:

name: github pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          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
        with:
          hugo-version: '0.74.3'
          extended: true

      - name: Build
        run: hugo --minify

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

So this basically checks out each new push to the main branch, takes care that Hugo Extended is available and runs it to build the static page in the local ./public  directory. This is then taken and put into a new commit on the gh-pages branch which will in turn lead to an update of the static hosted page.

Et Voila!

Coming soon…

… to a nameserver near you

Yeah so now the next thing to figure out and switch over is my old trusty html based and Apache hosted homepage. This basically means setting up A and CNAME records to point to GitHub and also configure the GitHub side such that the vhost / CNAME is recognized.

Hopefully this will turn this

into that

very soon.