GitHub Actions Self-Hosted Mac Runner: How to Deploy? 2026

Workflow needs macOS, and the Mac can stay reachable → register a self-hosted Runner, configure its service, and verify a real job before relying on it.
If your workflow is cross-platform and does not need Mac tools, use a hosted Runner instead.

This guide is for independent iOS and macOS developers who need Mac-based Actions jobs, freelancers setting up a client build environment, and small remote teams deciding who will maintain a persistent Runner.

Start with the deployment decision

A GitHub Actions self-hosted Mac Runner makes sense when a workflow needs macOS or software available only on a Mac, and someone can maintain the host. It is not a default upgrade for every GitHub Actions project. A hosted Runner is usually simpler for ordinary cross-platform jobs because GitHub manages its machine environment; a self-hosted Runner puts host upkeep, availability, and access control on your team. GitHub explains the distinction in its self-hosted Runner overview.

Before setup, identify the job that requires a Mac. It might depend on an Apple platform build tool, a macOS-only test, or a locally installed dependency. Then check whether the Mac can remain powered on, connect to GitHub, and retain the project environment between jobs. GitHub lists the operating system and software requirements for self-hosted systems in its Runner system requirements.

This is also an ownership decision. A self-hosted Runner is not just a different place to execute the same workflow. It gives workflow code a route to a machine your team is responsible for. GitHub’s self-hosted Runner documentation outlines that responsibility.

Prepare the repository and Mac before registering

Choose the Runner’s scope first. A repository-level Runner is associated with one repository; an organization-level Runner can be made available across repositories according to the organization’s configuration. Pick the narrowest scope that meets the project’s needs. You need permission to manage Runner settings at that scope.

On the Mac, confirm that you can sign in, reach the project files, and install the dependencies required by the workflow. Decide where the Runner application and working directory will live. Avoid placing project secrets in general-purpose shell startup files or in a directory that unrelated users can read.

Use the GitHub settings page for the chosen repository or organization to generate the current registration instructions. Select macOS and the architecture that matches the host. Do not copy commands from an old note or another machine: the URL, token, and available labels are specific to the setup flow and Runner registration. GitHub’s add a self-hosted Runner instructions show this process.

Registration does not validate the project’s build dependencies. Treat it as a separate setup milestone, not evidence that a production workflow is ready.

Register the Runner using GitHub’s current instructions

Open the settings page for the scope you selected and follow the displayed macOS instructions. GitHub provides a generated registration process, including the Runner download and configuration steps. Use the commands and values from that page at the time of deployment. The example below shows the shape of a registration command, not a substitute for the current values:

./config.sh --url <GITHUB_REPOSITORY_OR_ORGANIZATION_URL> --token <TEMPORARY_TOKEN>

Do not place the token in a checked-in script, a workflow YAML file, or a shared document. Do not publish terminal output that reveals it. If the registration flow fails, return to GitHub settings and follow the current guidance rather than trying an old token.

When setup completes, check that GitHub lists the Runner as available for the selected scope. Also inspect the labels shown there. Labels are how a workflow can select a Runner with the required operating system or capabilities; GitHub explains how to apply labels to self-hosted Runners.

A successful registration confirms that GitHub recognized the Runner. It does not confirm that the Runner will survive a terminal closing, a Mac restart, a network interruption, or a project-specific build.

Keep the Runner available beyond the terminal session

A foreground Runner process is tied to the terminal session in which it was started. If that session ends, the process stops. To run it independently, follow GitHub’s current macOS service procedure. The official macOS service configuration guide describes how to install, start, and check the service.

From the Runner directory, the service commands follow this pattern:

./svc.sh install
./svc.sh start
./svc.sh status

Use the permissions and exact sequence shown in the current GitHub instructions. The service installation and status output may differ with the system’s current state. An illustrative status check might look like this:

Service is running

That line is only an example of the kind of result to look for, not a claim about a particular Mac or OnceMac host. A local service status check and GitHub’s online indicator answer different questions: one reports the service on the Mac; the other shows whether GitHub can see the Runner.

Do not stop at the first successful start. Restart the Mac using the same method you expect to use during normal maintenance. After the machine comes back, check the service status and the Runner’s state in GitHub. If the Runner does not return online, inspect the service logs and follow GitHub’s Runner monitoring and troubleshooting guidance.

For travel and remote work, include the Mac’s power state, network access, and remote recovery method in the operational plan. A service can start automatically and still be unable to accept jobs if the host is offline or cannot reach GitHub.

Route a controlled workflow and verify the full build path

A workflow must request labels that match the registered Runner. GitHub’s label guidance describes the available Runner labels and how to use them. A typical pattern is:

jobs:
  macos-check:
    runs-on: [self-hosted, macOS, ARM64]
    steps:
      - uses: actions/checkout@v4
      - name: Confirm the job reached the Mac
        run: |
          sw_vers
          uname -m

This is a sample dispatch pattern, not a guarantee that those labels match your host. Confirm the labels in the GitHub settings for the actual Runner. Use the project’s existing approved actions and dependency setup; do not copy a sample workflow into a production repository without reviewing what it executes.

Start with a low-risk, repeatable job. Check that GitHub assigns the job to the intended Runner, that the logs are visible, and that the expected artifact or test result is produced. Then run the project’s actual macOS CI build, including the tools and dependencies it requires. One successful test proves only that this specific job ran under those conditions. It does not establish compatibility for every project or workflow.

If the job stays queued, check whether the Runner is online and whether the workflow’s requested labels match. If it starts on the wrong machine, narrow the labels or scope. If the job fails during dependency installation, separate that issue from Runner registration and service health. GitHub’s monitoring and troubleshooting documentation provides the official path for interpreting Runner problems.

Set security and maintenance boundaries before travel

A self-hosted Runner executes workflow code on its host. That makes trust in the workflow and the people who can change or trigger it a central part of deployment, not an afterthought. GitHub’s secure use reference warns that self-hosted Runner environments can be exposed to risks from untrusted workflow code, including code from public repository contributions. A persistent host may retain job files or other state unless your process removes them.

Before enabling jobs, review who can alter workflow files, who can trigger runs, which secrets are available to each job, and what the Mac can access outside the project. Avoid routing untrusted external pull-request code to a persistent host that can reach private files, signing material, or unrelated services. If a project must test external contributions, use a security design that isolates that work rather than treating repository visibility as a safety control.

Assign an owner for Runner updates, dependency changes, job cleanup, and recovery checks. Keep a short runbook with the Runner scope, label names, service status procedure, and the steps for replacing or re-registering the host. Do not put registration tokens or long-lived secrets in that runbook.

FAQ

How do you add a self-hosted macOS Runner?

Choose a repository or organization scope in GitHub settings, select macOS and the matching architecture, then use the instructions generated for that scope. Keep the temporary registration token private. After configuration, check that the Runner is listed and online before asking a workflow to use it.

Can a Mac Runner accept jobs after Terminal closes?

A Runner started in the foreground stops when its process ends. Configure the Runner as a macOS service if it must operate independently of an open terminal. Then verify the service status and GitHub’s online state; the Mac still needs power and network access.

How do you make a Mac Runner start after reboot?

Follow GitHub’s macOS service setup, then restart the Mac and test the result. Check both the local service status and the Runner’s state in GitHub. Do not assume a successful initial registration proves that the service will return after a restart.

Should public pull requests run on a persistent Mac Runner?

Not when the workflow code is untrusted and the host can access sensitive files or credentials. Limit who can trigger and modify jobs, scope secrets carefully, and separate external contribution tests from a persistent host with private access.

If your current setup depends on a laptop that travels with you, a local machine that must stay awake, or a workflow that becomes unavailable when the device is lost or disconnected, a remote Mac can be an alternative. Those approaches still have real trade-offs: local hardware must travel and remain reachable, while any persistent remote Runner still needs careful permissions and maintenance. If the project has passed the registration, service, and workflow checks, review OnceMac’s available options and confirm the access method, macOS environment, and rental period against your actual workflow before choosing. For a project-specific fit check, contact OnceMac with the Runner requirements and the way the host will be used.

Frequently asked questions