I am migrating my repositories from GitHub to Codeberg, which is built on Forgejo. As an iOS engineer, I need automation support on macOS—a feature not currently available among Codeberg’s Forgejo runners. This post details how I built the required Forgejo runner binary on my Mac to address this need.

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!