Enabling Gitea actions with act_runner on macOS via Homebrew

To enable Gitea Actions (GitHub Actions–compatible workflows) you’ll need the act_runner utility, which connects your Gitea instance to its built-in CI system. 

TL:DR – The

Install the action runner

Homebrew makes this straightforward.

brew install gitea-runner

Once installed, register the runner with your Gitea server:

act_runner register

You’ll be prompted for:

• Instance URL – your Gitea URL, e.g. https://git.yourservername.co.uk:3000/
• Registration Token – found under Site Administration → Actions → Runners → Create Runner

This creates a configuration file at:

~/.config/act_runner/config.yaml

Make sure this config file contains:

labels:
     - "macos-latest:host"

You can now start the runner as a background service:

brew services start gitea-runner

Or, if you prefer to manage it yourself, create a LaunchAgent in the same style as your Gitea service. The runner will automatically pick up workflows defined in .gitea/workflows/ and execute them locally when triggered.

Troubleshooting self-hosted runners on macOS

Running act_runner natively on macOS works well, but there are a few quirks to be aware of. The runner executes workflows directly on your Mac rather than inside Docker, so make sure your job definitions don’t depend on Linux-only paths or container tools. Set this explicitly in /opt/homebrew/etc/act_runner/config.yaml

runner:
  name: macos-runner
  executor: host

Because macOS sandboxing can block subprocesses or network calls, ensure your user account has full disk and developer tool permissions under System Settings → Privacy & Security.

If you’re running act_runner as a background service (via Homebrew or a LaunchAgent), verify that the environment variables match your shell environment — for example, paths to compilers or language SDKs might differ. You can debug jobs locally by running:

act_runner exec --job <job-name>

This runs the job interactively in your current session, showing full logs and helping to confirm your workflow runs as expected before automating it.

See also Running Gitea with Let’s Encrypt on macOS via Homebrew