Build Hugo

Build Hugo is a GitHub Action for building static websites with Hugo, the static site generator, by wrapping the Hugo extended binary in a Docker container based on debian:bookworm-slim. It lets any GitHub repository compile a Hugo project in CI without installing Hugo manually, and it is published under the lowply/build-hugo repository.

What is Build Hugo?

Build Hugo is a GitHub Action that runs the Hugo extended binary (version 0.164.0) inside a Debian-based container to generate static site output. As input it takes a Hugo project directory from the checked-out repository, and as output it produces the built public/ folder that can be deployed or uploaded. The action is designed to drop into any GitHub Actions workflow as a single step after checkout.

Key Features

Build Hugo bundles the Hugo extended binary and the debian:bookworm-slim base image into a single action, with tags that track official Hugo releases. Its concrete features include:

• Version-aligned tags — Tag names like v0.164.0 and v0.68.3 match Hugo's own release tags, so you can pin an exact Hugo version for your build.
• Docker-based reproducibility — The action uses debian:bookworm-slim as the base image; versions 0.148.1 and later use this base, avoiding the broken debian:buster-slim mirrors noted in the README.
• Simple workflow integration — Add it after actions/checkout@v2; no extra setup like downloading Hugo or configuring environment variables is needed.
• Local build option — Run docker run --rm -w /tmp -v $(pwd):/tmp lowply/build-hugo:v0.164.0 to build the same way outside CI for testing or debugging.
• Automated version updates — The repository provides ./script/update.sh to open a PR for a new Hugo version and ./script/release.sh to publish the updated action after tests pass.
• Extended Huffman support — Uses the Hugo extended edition, which includes the Rollup/PostCSS/Webpack integration needed for some themes and asset pipelines.

Who is it for?

Build Hugo is for developers and teams who compile Hugo static sites in GitHub Actions and want reproducible, pinned Hugo versions. It fits these roles:

• Hugo site maintainers — Add it to a workflow to build the site on every push or pull request.
• Developers testing multiple Hugo versions — Use different tags (e.g. v0.68.3, v0.148.1) in a CI matrix to verify compatibility.
• CI pipeline engineers — Replicate exact build behavior locally via the included Docker command, reducing debug cycles.

How does Build Hugo work?

Build Hugo works by running the Hugo command inside a Docker container built from the lowply/build-hugo image. In a GitHub Actions workflow, you check out your code, then reference the action with a tag matching the needed Hugo version, e.g. uses: lowply/[email protected]. The README shows a complete workflow example with on: [push].

What can you do with Build Hugo?

With Build Hugo you can build Hugo sites without installing the Hugo binary on the GitHub runner. For example:

• Generate static HTML — Run the action in a push-triggered workflow to produce the public/ directory for deployment.
• Test across Hugo versions — Use a matrix of action tags to check a site against multiple Hugo releases.
• Build locally — Execute the Docker command from the README to reproduce CI output on your own machine.
• Avoid dependency steps — Replace manual Hugo installation and version management with one straightforward action step.

FAQ

Is Build Hugo free to use?

Yes. The GitHub Action and its Docker image are free and open source, published in the lowply/build-hugo repository. You only pay for standard GitHub Actions minutes when you run it in CI.

Can I use a specific Hugo version other than 0.164.0?

Yes. The action's tags mirror Hugo's release tags, so you can specify v0.68.3 or any other published tag. Versions 0.148.1 and newer are recommended because earlier tags rely on the debian:buster-slim base image whose mirrors are currently broken.

Does Build Hugo support Hugo modules and extended features?

The action uses the Hugo extended edition, which supports features such as asset pipelines and modules. The exact capabilities depend on the Hugo version you pin via the action tag.

How do I run Build Hugo locally?

The README provides the command docker run --rm -w /tmp -v $(pwd):/tmp lowply/build-hugo:v0.164.0. It mounts your current directory into the container at /tmp and runs the Hugo build from there, giving you the same output as the GitHub Action.

How is the action versioned?

Every Hugo release gets a corresponding tag on the lowply/build-hugo repository. Maintainers use ./script/update.sh to create a pull request for the new version and ./script/release.sh to publish it after tests pass, so tags stay aligned with Hugo releases.