In this article we will see how to automate the build and deployment of a Hugo-based CV site hosted on GitHub Pages. No more running Hugo by hand, just git push and you're done.

The purpose of this article is not to introduce Hugo or GitHub Pages from scratch, but instead to explain how to wire them together with GitHub Actions to get a clean, automated deployment pipeline for a developer CV site.

💡 My CV site is live at reservoircode.net so feel free to use it as a reference !

The context

My CV is a static site generated with Hugo and hosted on GitHub Pages. The theme is hugo-devresume-theme added as a git submodule. The whole content is controlled by a single config.toml file for the experiences, skills, languages, everything...

Before setting up the automation, my workflow was manual:

hugo
git add .
git commit -m "Bla bla bla"
git push origin master

Not great. Let's fix that 😃

Branch strategy

The key idea is to separate sources from the generated output:

Working on src, pushing triggers the build, master gets updated automatically.

The GitHub Actions workflow

Create the file .github/workflows/deploy.yml on your src branch:

name: Deploy Hugo site

on:
  push:
    branches:
      - src

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.81.0'
          extended: true

      - name: Build
        run: hugo --source src

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./src/public
          publish_branch: master
          cname: reservoircode.net

A few things worth noting here:

submodules: true. The theme is a git submodule. Without this flag, the clone would be incomplete and the build would fail silently.

extended: true. This is critical. The theme uses SCSS with Hugo template variables injected at build time (like primaryColor). Without the extended version of Hugo, the SCSS is not compiled and your custom colors are simply ignored and the theme falls back to its hardcoded defaults.

cname. If you use a custom domain, this line regenerates the CNAME file on every deploy. Without it, the file gets wiped on each push and your domain stops resolving.

github_token. Automatically provided by GitHub, no manual secret setup needed.

Pitfalls I ran into

Setting a custom font color with SCSS

After the first successful deploy, my custom blue color (#53abe7) was replaced by the theme's default green (#54B689). The root cause: Hugo standard cannot process SCSS. The theme's stylesheet contains Hugo template directives like:

$theme-color-primary: {{ .Site.Params.primaryColor | default "#54B689" }};

Without Hugo Extended, this variable is never injected and the default value is used. Adding extended: true to the workflow fixed it.

Setting avatar image

The assets/ folder in Hugo is processed through a pipeline and its path gets concatenated with the base path. The fix is to place static files under static/ instead and Hugo copies its content as-is to the root of the generated site.

mkdir -p src/static/assets/images
cp my-photo.png src/static/assets/images/avatar.png

Be careful of baseURL

The site is served from reservoircode.net. Hugo uses baseURL to build all absolute paths for images, CSS, JS. Updating it fixed the remaining broken assets:

baseURL = "https://reservoircode.net/"

Customizing the theme without touching it

The theme's layout files live in src/themes/devresume/layouts/partials/. If you modify them directly, your changes get wiped next time you update the submodule.

Hugo has a clean override mechanism: any file placed under src/layouts/partials/ takes priority over the theme's version. So to customize experience.html:

mkdir -p src/layouts/partials
cp src/themes/devresume/layouts/partials/experience.html src/layouts/partials/experience.html

Then edit src/layouts/partials/experience.html freely. Your version will always win.

I used this to add a stack field to each experience entry. In config.toml:

[[params.experience.list]]
title = "Lead Developer / Senior Software Engineer"
dates = "02/2025 – Present"
company = "Rout'in · Reservoir Code · Hybrid"
stack = "Java 25, Spring Boot 3, React, AWS, Terraform, EKS"
details = """
Tech Lead for a team of 3 to 4 developers on the **Mobility Pass** platform...
"""

And in the overridden partial:

<div class="item-content">
    <p>{{ with .details }}{{ . | markdownify }}{{ end }}</p>
    {{ with .stack }}
    <p><strong>Stack :</strong> <span class="text-muted">{{ . }}</span></p>
    {{ end }}
</div>

Markdown in config.toml

Since the theme uses | markdownify in its templates, you can write Markdown directly in your config.toml strings. Use triple quotes for multiline content:

details = """
Led integration with a **major French payment service provider**.

Ran bi-weekly coordination meetings with OPS teams.
"""

⚠️ Watch out for indentation. In Markdown, 4 leading spaces mean a code block. Keep your content flush left inside the """ block.

Updating the theme submodule

The theme is pinned to a specific commit. To pull the latest version:

cd src/themes/devresume
git checkout master
git pull origin master
cd ../../..
git add src/themes/devresume
git commit -m "Update theme"
git push origin src

The git add src/themes/devresume step updates the commit pointer stored in your repo. Without it, the submodule stays pinned to the old version.

Conclusion

The setup is now clean: edit config.toml on src, push, done. GitHub Actions handles the Hugo build and deploys the result to master, which GitHub Pages serves on the custom domain for CNAME included.

The main lesson from this experience: Hugo Extended is not optional when your theme compiles SCSS at build time. And the branch separation between sources and output is the right model for GitHub Pages, even if it requires a small upfront setup.

Have a good day ☀️

Tags: hugo github devops webdev