I had been planning to start a blog for some time, collecting topics and testing Jekyll on GitHub Pages. As part of my move to Codeberg, I set up the blog as a proof of concept for hosting my repositories and evaluating Codeberg’s Pages service. For my trial, I simply created the initial Jekyll page with no fancy content. My focus was on trying out the process of publishing the blog site. Eventually, this very blog containing this post emerged from the trial.

Jekyll static site generator

To create a static web page with Jekyll, we only need the things listed in the Jekyll Quick Start Guide, which includes:

  • Ruby with RubyGems
  • installing Jekyll and Bundler via RubyGems.
  • create a new site
  • have Jekyll generate it.

The Jekyll documentation offers a guide on how to install the necessary requirements for various platforms.

Codeberg pages

The Codeberg Pages service converts the content of a repository into a static website. You can deploy the page via a Webhook or a Forgejo action.

The Webhook option publishes the repository’s content without any pre-processing. However, since I use Jekyll as a site generator, pre-processing is necessary as the static content of the site needs to be generated first. Therefore, publishing the site using the Forgejo Action may be the preferred option.

Running the Forgejo Action

The first attempts to use the action was using one of the Actions runners Codeberg provided.

on:
  workflow_dispatch:
    input: []
  push:
    branches: [blog]

jobs:
  publish-blog:
    runs-on: codeberg-tiny
    steps:
      - name: Check out the repository
        uses: https://data.forgejo.org/actions/checkout@v6
      - name: Setup build environment
        run: bundle install
      - name: Build ANGU Software Blog
        run: bundle exec jekyll build
      - name: Publish blog
        uses: https://codeberg.org/git-pages/action@v2
        with:
          site: "https://$.codeberg.page/angu-software-blog/"
          token: $
          source: _site/

Unfortunately this didn’t work because the runner did not had ruby and bundler installed, which is required for Jekyll to build the site.

The workflow would fail already before the git-pages action would be triggered.

(x) Setup build environment
/var/run/act/workflow/1.sh: line 2: bundle: command not found
⚙️ [runner]: exitcode '127': command not found, please refer to https://github.com/nektos/act/issues/107 for more information

I decided to not bother to install a ruby environment on the Codeberg runner, instead to use my own MacBook as a self-hosted runner.

I adapted the workflow to use my self-hosted macOS forgejo runner and gave it a go.

# ...
jobs:
  publish-blog:
    runs-on: angu-mac
# ...

Again no luck. Although the site generation succeeded the git-pages action failed.

(x) Publish blog
⚙️ [runner]: unable to evaluate current system architecture: unable to get docker info to determine current system architecture [...]

It seems the action tries to determine the os it is running on but fails to do so.

The pragmatic workaround

Since the git-pages action was not an option for now, what were the alternatives?

I came up with a simple pragmatic solution:

  • Create a separate pages repository on Codeberg
  • Run a custom script which builds the site and pushes the generated content to the page-repository

The publish script implements the following steps:

  1. Generate the site
  2. Check out the pages repo
  3. Replace the repo content with the newly generated content
  4. Push an update to the pages repo

The script is executed on every commit to main of the Jekyll repository.

This works! The curl-it is that I now have two repositories to maintain. Which is acceptable for now since one is basically just a storage of the generated page content which happen to be able to be rendered by the Codeberg pages service.

Another alternative

I reported the issue of the Forgejo Action. During the discussion an alternative approach was suggested as a workaround on a macOS runner. The suggestion was to simply run the commands the action would do with a matching git-pages binary for my MacBook runner architecture.

I could even install the git-pages binary on my macOS runner and just call it instead of downloading it on every run. This works because git-pages is also available on Homebrew, or just download it fro the git repo.

This seems like a feasible solution, but I did not tried it yet.

Conclusion

There are always multiple solutions to a problem. Sometimes a very pragmatic approach leads to success when an obvious one is failing.

By creating a separate pages repo and pushing the generated Jekyll site on every commit I managed to enable site deployment in minutes, while the obvious choice to use the existing forgejo actin failed to detect my runners platform.

I still plan to improve on the solution and omit the extra repository by either directly using the git-pages CLI or even fixing the Forgejo action.