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.

Building Forgejo runner binary

The Forgejo Runner is a daemon that fetches workflows to run from a Forgejo instance, executes them, sends back with the logs and ultimately reports its success or failure.

Forgejo does not provide a binary for macOS among the many Linux distributions.

The Forgejo runner repository README.md, however, states that we can build our own runner binary:

Building

• Install Go and make(1)
• make build

After downloading and installing The Go Programming Language for macOS, we can use the following script to clone the Forgejo Runner repository on a specific version and compile the binary:

#!/bin/zsh
set -e

# clone repo
echo "[INFO] Cloning Forgejo Runner repo ..."
git clone "https://code.forgejo.org/forgejo/runner.git" "forgejo-runner"
cd "forgejo-runner"

# Check out revision
RUNNER_VERSION_TAG="v12.6.4"
echo "[INFO] Checking out version $RUNNER_VERSION_TAG ..."
git fetch --tags
git checkout $RUNNER_VERSION_TAG

# build runner
echo "[INFO] Build runner ..."
make build

echo "[INFO] Successful build '$(forgejo-runner -v)'"

Once the script has been executed, we can find the macOS Forgejo Action Runner binary in the current directory

$ ./build-forgejo-runner.sh
[INFO] Start building Forgejo Runner v12.6.4 ...
[INFO] Cloning Forgejo Runner repo ...
[INFO] Checking out version v12.6.4 ...
[INFO] Build runner ...
[INFO] Successful build 'forgejo-runner version v12.6.4'

Using the runner

Once we have built the runner for macOS, we can follow the Forgejo Runner installation guide to register and start the runner.

To avoid memorizing steps or repeatedly consulting the docs, I created a management tool: forgejo-runners-management.

The tool includes scripts for:

• building a runner binary for macOS
• registering a runner on Codeberg
• starting runners

This makes it much easier to manage even multiple runners on a single machine.

Conclusion

While Codeberg and Forgejo do not provide Action Runners for macOS out of the box, building a macOS binary is entirely possible.

The forgejo-runners-management tool simplifies the process and makes managing runners both convenient and enjoyable.

Happy forging!