Register macOS runner on forgejo (macos-latest)

[ulises-c]

The Forgejo instance at ollie-server needs a macOS runner for SwiftUI build & test CI.

Why: swift build and swift test require Apple frameworks (SwiftUI) and cannot run on Linux. Only lint/format/spellcheck can run on the Linux runner.

Steps:

• Install forgejo-runner on a Mac
• forgejo-runner generate-config > ~/forgejo-runner/config.yml
• Get registration token from Forgejo → Settings → Actions → Runners
• forgejo-runner register --instance <SERVER-URL> --token <TOKEN> --name <NAME> --labels macos-latest
• Register as a LaunchAgent or run forgejo-runner daemon

Prerequisites: Xcode (or Command Line Tools), Homebrew

Note: Can be your personal Mac — keep the daemon running for CI.

[ulises-c]

Seems there is no official Forgejo runner for macOS

• https://codeberg.org/forgejo/discussions/issues/447

Potential solutions

1. https://github.com/rafntor/Forgejo-runner-darwin-builder
2. https://codeberg.org/Pasee/RunnerHub

[ulises-c]

There are no official macOS binaries for forgejo-runner, but you can build it from source since it is pure Go with no cgo:

brew install go
git clone https://code.forgejo.org/forgejo/runner.git
cd runner
make build
cp forgejo-runner ~/.local/bin/

This produces a native ARM64 binary that runs on macOS. Tested with runner version v12.10.2+20-g22ebc7d1.

Alternatively, you can serve it from: https://github.com/Crown0815/Forgejo-runner-windows-builder/releases (community builds, mostly Windows but sometimes macOS too).

[ulises-c]

The binary is working. To actually run it, we need to do the registration. Let's start:

1. Generate config

forgejo-runner generate-config > ~/forgejo-runner-config.yml

2. Then register (need a token from Forgejo UI)

forgejo-runner register \
  --instance <URL> \
  --token <TOKEN> \
  --name <NAME> \
  --labels macos-latest \
  --config ~/forgejo-runner-config.yml

3. Start the daemon

forgejo-runner daemon --config ~/forgejo-runner-config.yml
Go to your Forgejo web UI → Settings → Actions → Runners → "Create Runner" to get the token.

[ulises-c]

Working setup on macOS

The runner is now registered and running as a LaunchAgent. Here's the complete working process end-to-end.

1. Generate config

forgejo-runner generate-config > ~/forgejo-runner-config.yml

2. Register

forgejo-runner register \
  --instance http://<SERVER>:<WEB_UI_PORT> \
  --token <TOKEN_FROM_FORGEJO_UI> \
  --name <MACHINE_NAME> \
  --labels macos-latest \
  --config ~/forgejo-runner-config.yml

Token from: Forgejo → Settings → Actions → Runners → "Create Runner"

After registration, the credentials are written into ~/forgejo-runner-config.yml under a server.connections block. The runner.file: .runner field in the config is unused when server.connections is present.

3. Fix the URL (common gotcha)

The registration writes the URL using whatever you passed to --instance. If you accidentally used the SSH port instead of the web UI port, the daemon fails with:

tls: first record does not look like a TLS handshake

Check the url: field under server.connections in the config and make sure it points to the HTTP web UI port, not the SSH port.

4. Start the daemon

forgejo-runner daemon --config ~/forgejo-runner-config.yml

5. Register as a LaunchAgent (auto-start on login)

Create ~/Library/LaunchAgents/net.forgejo.runner.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>net.forgejo.runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/<USERNAME>/.local/bin/forgejo-runner</string>
        <string>daemon</string>
        <string>--config</string>
        <string>/Users/<USERNAME>/forgejo-runner-config.yml</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/<USERNAME></string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/<USERNAME>/Library/Logs/forgejo-runner.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/<USERNAME>/Library/Logs/forgejo-runner.log</string>
</dict>
</plist>

Then load it:

launchctl load ~/Library/LaunchAgents/net.forgejo.runner.plist

Verify it's running:

launchctl list | grep forgejo
# → <PID>  0  net.forgejo.runner

Managing the service

# Stop + disable
launchctl unload ~/Library/LaunchAgents/net.forgejo.runner.plist

# View logs
tail -f ~/Library/Logs/forgejo-runner.log

[ulises-c]

Automation plan: macOS/forgejo-runner/

Why not Docker

The runner is registered as macos-latest:host — jobs run directly on the host to access Xcode/Swift. Running the runner daemon inside a container would sever that, making host execution impossible. Docker is the right model for Linux services (like the Forgejo server itself), but not for a macOS host runner.

Proposed folder structure

macOS/forgejo-runner/
├── .env.example          # FORGEJO_INSTANCE, RUNNER_NAME, RUNNER_LABELS, RUNNER_VERSION
├── install.sh            # build from source, install binary, write LaunchAgent, register
├── update.sh             # pull latest tag, rebuild, restart LaunchAgent
└── net.forgejo.runner.plist.template   # LaunchAgent with __USERNAME__ placeholder

Follows the same pattern as macOS/setup.sh and linux-server/<service>/.

---

install.sh responsibilities

1. Read .env (copy from .env.example, fill in values)
2. brew install go if missing
3. Clone https://code.forgejo.org/forgejo/runner.git, checkout $RUNNER_VERSION tag
4. make build, cp forgejo-runner ~/.local/bin/
5. forgejo-runner generate-config > ~/forgejo-runner-config.yml
6. Prompt: "Open $FORGEJO_INSTANCE/user/settings/actions/runners and paste your token:"
7. Run forgejo-runner register with the token
8. Inject __USERNAME__ into the plist template → ~/Library/LaunchAgents/net.forgejo.runner.plist
9. launchctl load the plist
10. Verify with launchctl list | grep forgejo

The token is never stored in the repo — only in ~/forgejo-runner-config.yml on the machine.

---

update.sh responsibilities

1. Fetch latest release tag from https://code.forgejo.org/forgejo/runner/releases (or git tag)
2. If already on latest, exit early
3. git pull, checkout new tag, make build, cp binary
4. launchctl unload → launchctl load to restart with new binary
5. Print version before/after

Can be run manually or wired to a launchd timer (StartCalendarInterval) for scheduled checks — similar to how Watchtower handles Linux container updates.

---

.env.example

FORGEJO_INSTANCE=http://<hostname>:<port>   # web UI URL (not SSH port)
RUNNER_NAME=<machine-name>
RUNNER_LABELS=macos-latest
RUNNER_VERSION=v12.10.2                     # pin to a tag; update.sh bumps this

---

Out of scope (not needed)

• Docker (wrong execution model for host runner)
• Watchtower (that's for container image updates)
• Separate config management — the generated ~/forgejo-runner-config.yml is the source of truth on each machine

[ulises-c]

Gotcha: Node.js not in PATH

JavaScript-based Actions (actions/checkout, actions/cache, etc.) require Node.js at runtime. LaunchAgents on macOS don't load shell profiles, so nvm's PATH setup never runs — the runner fails with:

Cannot find: node in PATH

Fix: add an EnvironmentVariables dict to the plist that explicitly includes the nvm node bin directory:

<key>EnvironmentVariables</key>
<dict>
    <key>PATH</key>
    <string>/Users/<you>/.nvm/versions/node/vX.Y.Z/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>

Place this before <key>WorkingDirectory</key>. Then reload the service:

launchctl unload ~/Library/LaunchAgents/net.forgejo.runner.plist
launchctl load ~/Library/LaunchAgents/net.forgejo.runner.plist

Note: update the version string in the path whenever you upgrade Node via nvm.

Why not brew install node? Homebrew installs latest stable, not LTS — you lose version control. The plist approach keeps nvm as your Node manager.