Self-Hosted Runner Setup (macOS)¶

This guide covers setting up a Gitea Actions self-hosted runner on macOS for building proof binaries.

Prerequisites¶

macOS with Apple Silicon (M1/M2/M3/M4)
Xcode Command Line Tools: xcode-select --install
Python 3.11+ via Homebrew or pyenv

Install the Gitea Runner¶

# Download the runner binary (check https://gitea.com/gitea/act_runner/releases for latest)
curl -sL https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-darwin-arm64 -o act_runner
chmod +x act_runner
sudo mv act_runner /usr/local/bin/

Register the Runner¶

Go to Site Administration > Runners (or your repository's Settings > Actions > Runners) on your Gitea instance.
Copy the registration token.
Register:

act_runner register \
  --instance https://code.botwork.se \
  --token YOUR_REGISTRATION_TOKEN \
  --name macos-arm64-runner \
  --labels macos-runner

The label macos-runner must match the runs-on value in the workflow matrix.

Run as a Service¶

Create a launchd plist so the runner starts automatically:

cat > ~/Library/LaunchAgents/com.gitea.act_runner.plist << 'EOF'
<?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>com.gitea.act_runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/act_runner</string>
        <string>daemon</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/YOUR_USERNAME/.act_runner</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/act_runner.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/act_runner.err</string>
</dict>
</plist>
EOF

# Replace YOUR_USERNAME, then load:
launchctl load ~/Library/LaunchAgents/com.gitea.act_runner.plist

Python Setup¶

The runner needs Python 3.11 for setup-python. Install via Homebrew:

brew install python@3.11

Or use pyenv if you manage multiple versions:

brew install pyenv
pyenv install 3.11
pyenv global 3.11

Verify¶

Check the runner appears as Online in Gitea's runner list.

Push a test tag to trigger the release workflow:

git tag v1.1.0-rc1
git push origin v1.1.0-rc1

Confirm both linux-x86_64 and macos-aarch64 jobs run.

Enable macOS Builds¶

Once the runner is verified, uncomment the macOS matrix entry in .gitea/workflows/release.yml:

- os: macos-runner
  platform: macos-aarch64