DevOps / CI-CD

GitHub Actions macOS Runner 2026: How to Configure a Remote Mac?

GitHub warns that pull requests from forks in public repositories can run untrusted code on self-hosted runners (GitHub’s runner security guidance). Use a remote Mac as a GitHub Actions Runner only when the workflow needs macOS or Xcode and you can restrict who triggers it. First limit repository access and workflow triggers; then register the runner, configure its service, and test it with a trusted project before adding signing credentials.

This guide is for independent developers building iOS apps with GitHub Actions, small teams maintaining a macOS build process, and developers who already have a remote Mac but have not connected it to CI.

Decide whether this runner belongs in your workflow

A GitHub Actions self-hosted runner lets a workflow job run on a machine you manage. That can provide the macOS environment an iOS build requires, but it also makes the machine part of your repository’s security boundary. The right decision depends on what code can reach it, what the runner can access, and whether the machine needs to stay available for jobs.

A self-hosted runner is a good fit when all of these conditions hold:

  • The workflow needs Xcode, macOS tools, or a project-specific environment already configured on the Mac.
  • The repository, branches, and people allowed to trigger the workflow are trusted.
  • Someone can maintain the Mac, update the runner application, review permissions, and investigate failed jobs.
  • The build can be tested without immediately granting access to signing identities or release credentials.

Hold off if untrusted pull requests can reach the runner, if the build requires a desktop interaction that has not been tested in a service session, or if nobody owns runner updates and recovery. A runner that appears online is not, by itself, evidence that it is safe or ready for releases.

Decision branches

  • If the repository is private or workflow access is tightly controlled, and the build needs Xcode, proceed with a remote Mac runner.
  • If an untrusted public pull request can trigger a job on a runner with secrets or access to other systems, do not assign that job to this runner. Separate the environment or use a runner you can safely discard.
  • If the project does not need macOS, use an environment suited to its actual build requirements rather than maintaining a Mac runner without a clear reason.
  • If the Mac is shared with interactive development, first test whether background jobs can use the required files and tools without disrupting the person using it.

GitHub documents runner registration at repository, organization, and enterprise scope. These scopes change who can manage or use the runner; select the narrowest scope that supports the intended workflow. See GitHub’s runner access management guidance before deciding where to register it.

Registration scope Consider it when Check before proceeding
Repository The runner is meant for one repository’s workflow Confirm who can administer the runner and which repository events can trigger jobs
Organization Multiple repositories need a shared runner under organization controls Review which repositories can use it and whether sharing creates unwanted access
Enterprise Runner management needs to be controlled across an enterprise Verify that the broader management scope matches the intended users and repositories

The scope is an access-management choice, not a substitute for controlling workflow triggers. Keep the runner off workflows that execute untrusted code, and do not assume that restricting the runner to an organization makes every job in that organization safe.

Prepare the Mac and verify the Xcode toolchain

Before registering the runner, confirm that you can log in to the remote Mac, reach GitHub from it, and run the project’s build tools. If the Mac is managed remotely, establish and test its connection first. The KuzCloud remote Mac help guide is a place to review access instructions when the host is provided through KuzCloud.

A network connection that works during an interactive session is a useful starting check, but it does not prove that a background service will have the same environment. Record how to access the Mac for recovery, and make sure an authorized person can reach it if a workflow fails or the runner goes offline.

Check Command or evidence Stop or continue
Active developer directory xcode-select -p Continue only if the path points to the Xcode installation intended for CI
Xcode command-line tools xcodebuild -version Continue only if the command runs and reports the expected installed toolchain
Project structure xcodebuild -list -project "App.xcodeproj" Confirm that the intended project and scheme are visible
Network and account access Log in to GitHub from the Mac and verify the repository is reachable Resolve access or connectivity problems before registering
Build requirements List required environment variables, files, tools, and any interactive steps Keep signing or release secrets out of the initial test

Apple documents how to install the Xcode command-line tools and how to select the active command-line tools directory. Use xcode-select -p to inspect the active developer directory. If the path or command output does not match the intended toolchain, stop and correct the Xcode selection before treating any CI result as valid.

Do not assume that a successful xcodebuild lookup proves the complete project can build. It confirms that the command is available and can inspect the project, not that the selected scheme, simulator destination, dependencies, signing settings, or build scripts are ready. Keep this stage focused on validating the toolchain and identifying project-specific inputs.

Register the Mac with the right access scope

Once the host and Xcode checks pass, add a macOS runner through the GitHub interface for the selected repository, organization, or enterprise. GitHub’s instructions for adding a self-hosted runner provide the current registration procedure and the commands for the selected scope.

Use the instructions shown in that interface for the runner application. The exact download and configuration commands can depend on the platform and current runner release, so do not copy a command from an old setup note without checking it against the current GitHub instructions.

On the Mac:

  1. Download the runner application using the instructions shown for the selected scope.
  2. Extract it into a dedicated directory owned by the account that will run the service.
  3. Run the configuration command GitHub provides, substituting the repository or organization URL and registration token shown there.
  4. Choose a descriptive runner name and labels that identify its operating system and intended use.
  5. Confirm in GitHub that the runner appears online before attempting a workflow.

Treat registration tokens and account details as credentials. Use placeholders in internal documentation, such as <RUNNER_URL> and <REGISTRATION_TOKEN>, rather than saving real values in a shared note or workflow file. Do not paste the token into a public issue, commit it to the repository, or reuse an old value on the assumption that it remains valid. Follow the current GitHub interface and runner documentation for token handling.

Labels help a workflow select an appropriate machine; they do not grant permission to execute safely. Keep labels accurate. Do not label a machine as ready for a job it cannot support, and do not rely on labels to isolate secrets from untrusted code.

Configure a service without assuming a desktop session

A runner started manually in a terminal can be useful for initial testing, but a machine that must accept jobs without an interactive login needs a service configuration. GitHub’s runner application and service instructions describe the supported macOS service flow. Use the service scripts included with the configured runner and follow the current instructions for installing, starting, checking, and stopping it.

After setup, verify two different states:

  • Local service state: The runner service is installed and running on the Mac.
  • GitHub runner state: The runner appears online and available in the intended repository, organization, or enterprise.

Either check alone is incomplete. A local process can be running while the host cannot communicate with GitHub. A runner can also appear online during an interactive session but fail to return after a restart if its service was not configured correctly.

A service session is not the same as an interactive desktop session. Test access to project files, environment variables, Keychain items, and any GUI-dependent tools under the actual service account. Do not treat desktop access or signing capability as proven until a workflow has verified it.

For the first trial, keep the job simple and avoid requiring a certificate, provisioning profile, or upload credential. If the build only works after a person logs in, stop and investigate the session difference before relying on the runner for unattended release work.

Connect a trusted workflow and run an Xcode build

With the runner online, create a small workflow that targets its labels and runs only from a trusted branch. GitHub explains how to select a self-hosted runner in a workflow. The runs-on value should match labels that the runner actually has.

Here is a structural example. Replace the checkout placeholder with a reviewed, immutable commit reference approved for the repository. Set the project, scheme, and destination to values that exist in the actual app.

name: macOS build

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  build:
    runs-on: [self-hosted, macOS]
    steps:
      - name: Check out source
        uses: actions/checkout@<REVIEWED_FULL_COMMIT_SHA>

      - name: Inspect Xcode project
        run: xcodebuild -list -project "$PROJECT_PATH"

      - name: Build app
        run: >
          xcodebuild
          -project "$PROJECT_PATH"
          -scheme "$SCHEME"
          -destination "$DESTINATION"
          build
        env:
          PROJECT_PATH: ${{ vars.PROJECT_PATH }}
          SCHEME: ${{ vars.SCHEME }}
          DESTINATION: ${{ vars.DESTINATION }}

This example is deliberately a build check, not a signing or App Store release pipeline. Before using it, define the project variables in the repository or adjust the workflow to match the project. A destination that is unavailable on the host, an invalid scheme, or a missing dependency should be treated as a configuration failure—not as proof that the runner itself is broken.

The workflow also uses a narrow permission declaration. GitHub’s workflow syntax documentation explains permission settings. Review permissions against the job’s actual needs and avoid granting write access by default. A checkout step does not justify unrelated repository permissions.

Start with a push from a trusted branch rather than a workflow that accepts code from arbitrary contributors. Verify each part of the run separately:

  • GitHub schedules the job to the intended runner rather than another machine.
  • The checkout step retrieves the expected repository revision.
  • The Xcode command uses the intended project, scheme, and destination.
  • The build log shows a successful result and identifies failures clearly.
  • No signing or upload secret is exposed to the test job.

Only after this check passes should the team consider adding archive creation, signing, or distribution steps. Keep signing and upload work separate from the initial runner test so a toolchain or scheduling issue cannot be confused with a credential or release configuration problem.

Accept the runner before assigning routine jobs

A green build is one piece of evidence, not a full acceptance decision. Check the runner’s status in GitHub and retain the workflow run link, the relevant build log, and the project settings needed to reproduce the test. GitHub’s runner monitoring and troubleshooting guidance can help investigate unavailable runners and job failures.

Use this acceptance checklist before moving routine work onto the Mac:

  • [ ] The runner is registered at the intended scope, and its access is limited to the repositories that need it.
  • [ ] The Mac can run the selected Xcode command-line tools under the account used by the runner service.
  • [ ] A trusted workflow is scheduled to the expected runner and completes a real project build.
  • [ ] Build logs are available to the people responsible for diagnosing failures.
  • [ ] The team has tested what happens when the service stops and starts again.
  • [ ] After a host restart, the service returns and GitHub reports the runner online.
  • [ ] Workflow permissions and allowed triggers have been reviewed.
  • [ ] Credentials are not present in workflow files, logs, or shared setup notes.

If the runner does not return after a restart, do not treat a manual terminal start as a permanent fix. Check the service state, account permissions, network access, and the runner’s GitHub status; then repeat the restart test. If the job reaches the Mac but Xcode fails, inspect the developer directory, project inputs, and the service-session environment before changing runner labels or permissions.

Maintenance is part of the deployment, not an optional follow-up. Assign an owner to review runner application updates, workflow changes, access scope, and failures. Keep a removal procedure: stop the service, remove the runner through the appropriate GitHub management interface, and verify that the Mac no longer accepts jobs. If a host may have exposed credentials, revoke or rotate affected credentials as part of incident handling.

Frequently asked questions

How do you connect a Mac you control to GitHub Actions?

Register a self-hosted runner in the repository, organization, or enterprise settings, then configure the runner application on the Mac with the URL and temporary token provided by GitHub. Choose labels that match the host, and verify its online state before assigning a workflow. Keep the token private and avoid placing it in committed files or shared documentation.

How can a remote Mac runner stay available?

Configure the runner as a macOS service using the instructions distributed with the runner application. Check the service locally and confirm the runner is online in GitHub. Then test a restart and run a trusted workflow. If the runner depends on a desktop login, Keychain prompt, or GUI action, it may not behave the same way in the background service session.

Can a GitHub Actions self-hosted runner run an Xcode build?

Yes, provided the Mac has the intended Xcode installation and the workflow uses a valid project, scheme, and destination. Check the active developer directory with xcode-select -p, confirm xcodebuild is available, and run a build before adding signing or upload steps. A successful tool lookup alone does not confirm that project dependencies or destinations are configured correctly.

Can a public repository use a macOS self-hosted runner?

Do not send untrusted public pull request code to a runner that has access to credentials, private files, or other systems. GitHub warns that fork pull requests can execute untrusted code on self-hosted runners. Restrict triggers and permissions, or use an isolated environment that can be safely discarded. A public repository’s runner availability is not evidence that every workflow is safe to run.

If the existing build setup depends on a developer’s local Mac, that machine can be unavailable when it is needed, tied up during interactive work, or difficult for a team to reproduce. A non-macOS host avoids managing a Mac but cannot supply Xcode’s macOS build environment. A remote Mac adds a persistent host, but it still requires access controls, service monitoring, and someone to handle failures; it is not a hands-off replacement for release operations.

Once a trusted workflow has proven that it needs a continuously available macOS environment, review the KuzCloud console and its remote Mac access guidance to decide whether a hosted Mac fits the team’s operating model. Keep the runner limited to the jobs and credentials it genuinely needs, and choose a different setup if the workload requires unmanaged public contributions or nobody can maintain the host.

Run Your macOS CI on a Dedicated Remote Mac

Provision a dedicated KuzCloud Mac mini M4 and connect to your runner over SSH or VNC.

Install the macOS build tools you need with full root access and no virtualization layer.