Deploy Hugo to Forgejo Pages

Hugo deploys cleanly when the workflow pins a Hugo version and publishes the generated public directory.

Pages

What this solves

You have a Hugo docs or website repository and want Forgejo-native static hosting.

Best fit

Fast documentation sites
Versioned static content
Self-hosted Git teams moving Pages off GitHub

How to think about it

Hugo is fast enough that most teams do not need a complex deployment pipeline. Pin the extended Hugo build when your theme needs Sass processing, run the production build, and publish the `public` directory produced by that exact commit.

Hugo build job

name: pages
on: [push]

jobs:
  build:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true
      - run: hugo --minify
      - run: test -f public/index.html

Practical path

01 Install the Hugo version your site expects.
02 Run the production Hugo build in Forgejo Actions.
03 Deploy the output directory to Pages and verify links before adding a custom domain.

When to choose another path

Pin the Hugo version if your theme is sensitive to renderer changes.

Fetch submodules when themes live outside the repository.

Preview taxonomy, sitemap, and canonical URLs before switching DNS.

Next resources

Pages docs

How Fjord Pages deploys static sites.

Actions docs

Workflow basics for deploy jobs.

CLI

Trigger and inspect deploy workflows.

Operations

Run the forge behind the site calmly.