Ask AI

How to run a self-hosted GitHub Actions runner on a Mac

Turn a Mac mini, or any Apple silicon Mac, into a runner for your GitHub Actions jobs.

Install Codemany on a Mac with Apple silicon and macOS 14 or later, sign in with GitHub and pick your repositories. Then set runs-on: [self-hosted, codemany] in your workflow. Each job gets a fresh, single-use runner on your Mac, and GitHub still schedules the jobs and shows the logs.

What you need

A Mac with Apple silicon, on macOS 14 or later. A Mac mini works as well as a laptop.
A GitHub account that can add runners to the repo: a repo admin, or an organization owner.
Room for the jobs. Each job needs about 4 GB of memory, 2 CPU cores and 15 GB of disk. An 8 GB Mac runs 1 job at a time; a 16 GB Mac runs 3.

Set up the runner

Install
Download Codemany, drag it to Applications and open it.
Sign in with GitHub
Choose Sign in with GitHub and enter the code the app shows on github.com. Your 14-day free trial starts by itself, with no card. Your token stays on your Mac.
Pick repositories
Choose repositories, or a whole organization, then Continue. Public repos stay off unless you turn them on for that repo.
Install the Codemany Runners App, if asked
Only when an account you picked doesn't have it yet: choose Install… and approve it on GitHub.
Change one line
Set runs-on in your workflow, as below, and push a commit.

Every step in detail: Get started with Codemany.

Send a workflow to your Mac

The codemany label sends the job to your machines and nowhere else. Keep self-hosted first so a job never lands on a GitHub-hosted machine by mistake.

name: build
on: [push]
jobs:
  build:
    runs-on: [self-hosted, codemany]
    steps:
      - uses: actions/checkout@v4
      - run: make test

If you also run Codemany on Linux, add macOS to keep the job on a Mac: runs-on: [self-hosted, macOS, codemany]. Every label is explained in Advanced › Runner labels.

Keep the Mac awake

Jobs stop when the Mac sleeps. Codemany keeps the Mac awake while jobs run, until 2 minutes after the last job. You can change that to while runners are online, or never.

Laptop: keep it plugged in, or use an external display when the lid is closed.
Low Power Mode lets the Mac sleep anyway, so turn it off on a runner.
The app can stay closed. Codemany's background service keeps running jobs.
Updates install themselves, after running jobs finish.

Tools your jobs get

Jobs use whatever is installed on your Mac: Xcode, Homebrew packages, Docker. Nothing is preinstalled. Codemany checks your tools every 30 minutes and adds labels a job can ask for, such as xcode and docker.

Downloads from actions/setup-node, setup-python and other actions/setup-* steps stay in a shared tool cache between jobs. Details: Advanced › Tools and caching. Building apps? See iOS and Xcode builds on your own Mac.

Run more jobs at once

Add another Mac, a Linux server or a cloud machine (Machines). Each machine takes one slot on your plan. $20/month includes 2 machines; each extra machine is $10/month (Pricing).

Questions

Do I have to keep the Codemany app open?

No. Codemany's background service keeps running jobs when the app is closed.

Does it work on an Intel Mac?

No. Codemany needs a Mac with Apple silicon on macOS 14 or later, so Mac runners are always ARM64.

Where do I see the job logs?

On GitHub, as usual. You can also watch jobs in the app (Overview and Runs), the menu bar, or at http://codemany.local:8825 from any device on your network.

Why does my job stay Queued?

Every label in runs-on must match a runner, so a typo keeps the job waiting. More fixes: Troubleshooting.

Is a self-hosted runner on my Mac safe?

A self-hosted runner is not a sandbox: jobs run as your user. Only run workflows you would run in your own terminal. Read Runner security and Security & privacy.