How to Deploy a Self-Hosted GitLab Runner on macOS? 2026 Guide
A GitLab job reaches a macOS runner, but the build fails because the runner session or Xcode environment is not ready.
Fastest answer: You can deploy a self-hosted GitLab Runner on macOS and use the shell executor for Apple-platform builds. Run it as the supported user-level LaunchAgent, not as a system LaunchDaemon, and only route trusted projects to it because shell jobs run on the host with limited isolation.
This guide is for engineers setting up GitLab CI/CD jobs for Xcode builds or iOS tests.
It also helps DevOps teams maintaining a Mac node from Windows or Linux, and teams deciding whether a remote Mac can support their pipeline.
Execution environment
Install GitLab Runner on the macOS host that will execute the job. Installing or operating the GitLab server on that Mac is a separate decision: a runner is an execution worker that connects to a GitLab instance, not a requirement to host the GitLab service locally.
Prepare job dependencies on the runner host. A shell job uses the host environment, so a repository checkout alone does not provide Xcode, signing assets, package managers, or project-specific tools. The GitLab macOS installation guide describes the supported installation context and service setup. Check its current instructions before installing or upgrading the runner binary.
Can GitLab Runner run on macOS? Yes. Install it on the Mac that will perform the work, register it with the intended GitLab instance, and select an executor that matches the build requirements. For native iOS and macOS work, GitLab recommends the shell executor; it runs scripts directly in the host environment rather than inside a container. See the shell executor documentation for its behavior and limitations.
Registration connects the runner to the intended project, group, or instance scope. Follow GitLab’s runner registration instructions and make sure the registration choices match the team’s access policy. Use placeholders in internal notes and scripts, such as <GITLAB_INSTANCE> and <RUNNER_NAME>. Do not paste registration tokens, private repository paths, or real hostnames into public examples.
Before accepting real work, make a minimal job report the host’s operating system and the tools it can find. A runner that registers successfully has not yet proved that it can build the project. It has only proved that GitLab can reach the runner process.
Session and service model
On macOS, the distinction between a user agent and a system daemon affects when the runner starts and which environment it inherits. GitLab’s macOS instructions specify a user-level LaunchAgent and state that a system LaunchDaemon is not supported for this runner setup. Do not copy a generic server-service recipe and substitute a different launchd service type. Check the GitLab macOS service instructions when configuring the node.
A LaunchAgent is associated with a user’s login session. A LaunchDaemon is a system-level service. Apple documents this distinction in its guide to creating launchd jobs. For a CI maintainer, the practical consequence is that the runner’s availability can depend on the runner account’s login state and the host’s restart behavior.
That relationship matters for jobs that use a graphical session, interact with a simulator, or depend on user-scoped credentials in the login keychain. A command-line build may work while a task that expects an interactive session fails. Treat simulator and signing tests as separate acceptance checks rather than assuming that a healthy runner process proves every Apple-platform workflow is ready.
GitLab’s macOS service guidance also makes restart behavior conditional on the configured login setup. Teams should test their actual reboot and login policy rather than assume a LaunchAgent behaves like a system daemon that is always available before user login. Automatic login may improve unattended recovery, but it changes the host’s security posture. Decide whether the convenience is acceptable for the physical and operational security requirements of the team.
Why not configure the runner as a LaunchDaemon? Because GitLab’s macOS runner documentation specifies the user-level LaunchAgent model and does not support the system-level daemon approach for this setup. Follow the documented service mode, then test what happens when the runner user logs out and when the Mac restarts.
Xcode toolchain readiness
A runner can be online while the build still uses the wrong developer directory or lacks a required component. Check the toolchain from the same account and execution context that runs CI jobs. A command that succeeds in an administrator’s interactive terminal may not describe what the runner process can access.
For a first inspection, record the active developer directory and the Xcode version from a CI job. For example, use xcode-select -p to report the selected developer directory and xcodebuild -version to identify the Xcode installation. If the project requires a particular SDK or simulator component, inspect that requirement directly and install components using Apple’s documented process for additional Xcode components.
Do not treat the standalone command-line tools as interchangeable with a full Xcode installation when the project needs Xcode-specific build or simulator capabilities. Apple explains how to install the Xcode command-line tools, but the project’s actual build requirements determine whether those tools are sufficient.
Use two kinds of evidence:
- Environment evidence: CI logs show the active developer directory and the Xcode version visible to the runner account.
- Workload evidence: A representative project build completes with the expected scheme, destination, and required dependencies.
Keep secrets out of diagnostic output. A useful log identifies the toolchain and reports the command result without printing signing credentials, private key contents, or sensitive environment variables.
Runner choice and risk
For Apple-platform CI, the shell executor is often the direct route to the host’s Xcode installation. Its trade-off is equally direct: jobs execute locally on the Mac under the runner account. It is not a container boundary, and a separate job does not automatically receive a clean, isolated host.
| Option | Where the job runs | Main decision point | Suitable when |
|---|---|---|---|
| macOS shell executor | Directly on the macOS host under the runner account | Host access is convenient, but job isolation is limited | The node accepts only trusted projects and the team manages its shared state |
| Container-based execution | Inside the configured container environment | Confirm that the required Apple toolchain and host capabilities are available in that architecture | The project’s toolchain requirements are compatible with the selected environment |
| Other isolated execution architecture | Depends on the team’s runner design | Validate Apple-platform support, credentials, and operational overhead before choosing it | Stronger separation is required and the design provides it |
The table is a selection aid, not a claim that every execution architecture can run every Xcode workload. Confirm compatibility for the actual project. GitLab describes the shell executor’s host-level behavior and security considerations in its executor documentation, and provides additional guidance on self-managed runner security.
Treat the Mac as a trusted build worker, not as a safe place to execute arbitrary contributions. Restrict which projects can assign jobs to it, control who can change pipeline configuration, and use a dedicated runner account with only the permissions its jobs need. Review whether one project’s scripts could read files, credentials, caches, or build products left by another project. A cleanup command can reduce stale files, but it does not turn a shared shell host into a strongly isolated environment.
Which executor should you use on macOS? For native iOS and macOS jobs that need the host’s Apple toolchain, GitLab recommends the shell executor. If the security model requires strong per-job isolation, do not describe shell execution as a container or assume that runner tags provide isolation; evaluate another architecture before assigning sensitive workloads.
Job routing and result evidence
A dedicated tag makes it easier to direct macOS jobs to the intended runner, but tags are routing labels, not security controls. Configure the runner’s tags in GitLab and use matching tags in the job definition. Review the runner’s project or group scope as well, so an unintended project cannot use the node. GitLab explains how to manage runner scope.
A minimal job can confirm routing and basic tool visibility:
macos_environment_check:
tags:
- macos-apple
script:
- sw_vers
- xcode-select -p
- xcodebuild -version
Replace macos-apple with a tag configured for the intended runner. Keep the example limited to diagnostics: the job should not print secrets or dump the full environment. For an initial acceptance run, review the job log and verify that the reported host and toolchain match the intended node.
Then run a representative build using the project’s actual scheme and configuration. Check that GitLab records the correct runner, the job log contains enough detail to diagnose failures, and the expected artifacts are available. A successful compile is not proof that simulator tests, code signing, or packaging work. Validate those capabilities in separate jobs that use the relevant project configuration and credentials.
The GitLab Runner registration process and the CI job’s tags have different purposes. Registration establishes the runner connection and scope; tags help select it for matching jobs. Validate both. If a job remains pending or lands on another runner, inspect the runner’s online status, assigned tags, scope, and the job’s tag requirements before changing the build commands.
Node availability and recovery
A CI node is useful only when it is available under the team’s actual operating conditions. Test the runner after the runner account logs out and after the Mac restarts. Record whether the process returns, whether the expected user session exists, and whether a diagnostic job can still reach the required toolchain. Do not infer restart behavior from a successful first registration.
Keep a maintenance record for Xcode changes, runner upgrades, signing asset renewal, and project dependency updates. After a toolchain update, repeat the environment check and a representative build before routing critical jobs to the node. When a job fails, preserve the relevant GitLab job log and the runner’s service log location, while removing secret values from any support bundle.
Use this acceptance checklist before assigning team workloads:
- [ ] The runner is installed on the macOS host that will execute the job.
- [ ] The runner uses the documented user-level LaunchAgent setup.
- [ ] The runner account can access the project’s required tools and files.
- [ ] CI logs identify the expected active developer directory and Xcode installation.
- [ ] A representative project build produces the expected result.
- [ ] Simulator, signing, and packaging requirements have been tested separately when needed.
- [ ] Only approved projects and trusted changes can use the runner.
- [ ] Runner tags and scope route jobs to the intended node.
- [ ] Logout, reboot, maintenance, and recovery behavior match the team’s expectations.
If the node passes only the environment check, treat it as a trial runner. If it passes project-specific builds and access controls, it may suit controlled team jobs. Assign critical pipelines only after the recovery process and toolchain maintenance procedure have also been tested.
For teams considering a remote Mac, verify the access method, rental period, and required toolchain conditions before deciding whether to attach it to a pipeline. Review the available Mac access options and check KuzCloud support information for operational details; confirm current availability rather than assuming a particular configuration or location.
Compared with a Mac node, trying to keep Apple builds on a Linux host cannot provide the same native macOS execution environment; relying on a developer’s workstation makes availability depend on that person’s machine and session; and buying hardware for a temporary or uncertain workload ties the team to a purchase and ongoing upkeep. If the pipeline needs a real Mac only for a defined project or evaluation period, renting a Mac through KuzCloud can provide a more flexible way to test the workflow before committing to owned hardware. Check the current terms on the KuzCloud plan page that applies to your needs, then verify that its access and maintenance conditions fit the runner’s LaunchAgent and security requirements.
Run Your macOS CI Workloads on KuzCloud
Provision a dedicated Mac mini M4 for your Apple-platform builds and tests.
Install Xcode and your CI toolchain with full root access on bare-metal macOS.