GitHub Actions for Hugo

GitHub Actions for Hugo (actions-hugo) is a GitHub Action that installs Hugo onto GitHub Actions runners so any workflow can build and deploy a Hugo static site. Built and maintained by peaceiris (Shohei Ueda), it runs as a JavaScript/TypeScript action, supports Linux, macOS, and Windows, and works with Hugo Extended and Hugo Modules.

What is GitHub Actions for Hugo?

GitHub Actions for Hugo is a setup action that downloads and installs a specified version of Hugo into the virtual machine running a GitHub Actions job. It takes a hugo-version input (a semantic version, 'latest', or a version read from a file) and, optionally, extended: true to install Hugo Extended; as output it makes the hugo command available to later steps in the job. Since version 2 the action is implemented in JavaScript/TypeScript rather than as a Docker container, so it completes in a few seconds instead of the roughly one minute a Docker base action took to pull and build an image.

Key Features

• Multi-OS support — Works on ubuntu-latest, ubuntu-20.04, ubuntu-22.04, macos-latest, and windows-2019 runners, covering the three major CI platforms.
• Hugo Extended and Hugo Modules — Set extended: true to install the extended build, which is required for SCSS/Sass processing; Hugo Modules are supported on all listed operating systems.
• Latest version option — Setting hugo-version: 'latest' fetches the current Hugo release from Homebrew Formulae, so you always build with the newest version.
• Fast execution — As a JavaScript action it installs Hugo in under a few seconds, compared with the minute-plus startup of the older Docker-based approach.
• Version syncing via .env — You can read a HUGO_VERSION variable from a .env file and pass it to the action, keeping Docker Compose and CI on the same Hugo version.
• Integration with deployment actions — The documented workflows pair with peaceiris/actions-gh-pages to publish the generated ./public directory to GitHub Pages.
• Cacheable Hugo Modules — The docs show how to set HUGO_CACHEDIR and use actions/cache to reuse downloaded module dependencies between runs.

Who is it for?

• Hugo site maintainers — Anyone who builds a Hugo website and wants automated builds and deployments on GitHub Actions.
• Documentation teams — Projects using Hugo-based documentation themes like google/docsy, which require Hugo Extended plus autoprefixer and postcss-cli; the page includes a full workflow for that stack.
• Open-source developers — Maintainers who need consistent Hugo builds across Linux, macOS, and Windows runners, or who want to pin the exact Hugo version used in CI and local Docker environments.

What can you do with GitHub Actions for Hugo?

• Build and deploy a Hugo site to GitHub Pages — Add the action to a workflow, run hugo --minify, then use peaceiris/actions-gh-pages to publish the ./public folder.
• Use the latest Hugo automatically — Set hugo-version: 'latest' and the action pulls the newest release from Homebrew Formulae.
• Build a Docsy site with Node.js tooling — Combine the action with actions/setup-node and run npm ci to handle autoprefixer and postcss-cli dependencies.
• Render AsciiDoc content — Add a Ruby setup, gem install asciidoctor, and alias the asciidoctor command with experimental attributes before running Hugo.

How does it work?

Add a step like uses: peaceiris/actions-hugo@v3 to your workflow's job, with inputs for hugo-version and optionally extended. The action downloads the requested Hugo binary and places it on the PATH; subsequent run steps can then invoke hugo directly. The official workflows also show checking out the repository with submodules and full history so themes and .GitInfo/.Lastmod features work.

FAQ

Is GitHub Actions for Hugo free?

Yes. The action is open source under an MIT License and free to use in any GitHub repository. There are no paid tiers or usage limits tied to this action.

Does it support Windows?

Yes. The action supports Windows 2019 runners in addition to Ubuntu 20.04/22.04 and macOS. All listed operating systems support Hugo Extended and Hugo Modules.

How do I install Hugo Extended?

Set the input extended: true in the workflow step, and the action installs the extended Hugo binary, which includes support for SCSS/Sass compilation.

How can I cache Hugo modules?

Define a HUGO_CACHEDIR environment variable, add an actions/cache step before your build, and use a cache key based on the hash of go.sum. The page provides a complete copy-paste workflow example.

What Hugo versions are supported?

You can specify any semantic version number as hugo-version, or use 'latest' to always get the current release. The action also supports reading a version from a .env file for synchronization with Docker Compose.