Deploying Hugo sites on Codeberg pages

Context that noone will read

Most of the people reading this will understand why Github is a platform we (as the open source community) wanna ditch. If you don’t, there’s too many reasons to list them here.

However, Github pages has been an immensely popular mean of distributing content over static pages at no cost. Gitlab went ahead and copied it, but it has its own issues as well.

The current popular self-hostable git forge, Forgejo, is a great alternative. In fact, there’s a public instance of it that is really great named Codeberg. It even develops its own Forgejo plugin named Codeberg Pages! But if you consult the documentation for this service, you’ll quickly realize the problem I had at first: there is no mention whatsoever of a pipeline to build a static site from sources (such as Hugo, a static site generator).

So what now? I first thought about making a CI pipeline, which is avalaible in forgejo, to build the site and update the repo by moving all created static files to the root (fate reference omg?) of the branch. This would have been probably a very messy and breakable idea.

But then, I realized there’s an action called git-pages. It even has a readme made for Codeberg explaining how it works! Why isn’t this in the documentation? No idea. Let’s get to work then!

The workflow, so you can learn how to do it yourself!

First of all, create a repo named pages if you want it to be accessible at <username>.codeberg.page, or any repo name will be accessible at <username>.codeberg.page/<repo-name>

Then, enable actions in the features list in the settings.

Finally, create the file .forgejo/workflows/hugo.yaml, and write this in it, modified to your liking:

on: [push]
jobs:
  test:
    runs-on: codeberg-tiny
    steps:
      - uses: actions/checkout@v4
      - name: Setup Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.25.6'
      - name: Setup Hugo
        uses: https://github.com/peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.154.5'
          extended: true

      - name: build
        run: hugo --minify
      - uses: actions/git-pages@v2
        with:
          # This workflow will only work correctly in https://codeberg.org/username/reponame.git !
          # Adjust the site name to match your username and repository name.
          # To publish to the index site, https://username.codeberg.page/, name your repository
          # either `username.codeberg.page` or `pages`.
          site: "PUT THE URL HERE"
          token: ${{ forge.token }}
          source: public/

And it should work! Yay!!! Well played. Have fun with you new site.

See you later on this blog! beep!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!