DevOps / CI-CD

GitLab Runner macOS: 2026 Enterprise Isolation Guide

A shared macOS Shell Runner has left source files, build artifacts, or signing material available to the next job.

The fastest safe decision is simple: share low-sensitivity builds only inside the same trust domain, place signing and release jobs on a protected dedicated Mac Runner, and use a mixed pool when several teams have different risk levels.

Who this guide is for

This guide is for platform teams managing several iOS projects and planning a shared GitLab macOS build pool.

It also serves security owners protecting certificates, Keychain data, and release credentials, plus IT and procurement leaders comparing purchased, leased, and mixed Mac Runner capacity.

GitLab Runner macOS isolation by trust boundary

The main risk is not the word “shared.” The risk is allowing jobs with different trust levels to execute under the same host identity, workspace, credential store, or network path.

GitLab confirms that the Shell executor runs jobs directly on the Runner host. Its official security guidance warns that this creates a high-risk boundary for the host and the network around it. A malicious or compromised job may therefore affect more than its own build directory. Review the GitLab Shell executor security guidance before approving any shared design.

A useful trust decision uses four signals:

  • Source sensitivity: public, internal, confidential, or restricted code.
  • Commit authority: employees only, approved contractors, or external contributors.
  • Execution origin: protected branches, merge requests, scheduled jobs, or manually triggered pipelines.
  • Release authority: compile-only, test distribution, store submission, or production release.

Do not group projects only by department. Two projects owned by the same department can still have different contributor models, signing permissions, or release impact.

The project–task–asset matrix

Build a matrix before selecting a Runner pool. Each row should represent a task rather than only a repository.

Task type Typical trust decision Host placement Required evidence
Unit tests for internal code Shareable inside the same trust domain Shared build pool Source and contributor review
Dependency-heavy integration build Shareable only after residue testing Shared or segmented pool Workspace and cache scan
Ad hoc merge request build Do not place on a sensitive host without review Lower-trust build node Route and negative-access test
Signed test distribution Restricted Protected signing node Credential scope and Keychain test
Store or production release Dedicated and protected Dedicated release Runner Protected pipeline and recovery evidence

Can a GitLab macOS Runner serve multiple projects? Yes, but only when those projects share a documented trust domain and the host, workspace, credentials, and network exposure have been assessed together. A shared Runner is not a safe default for unrelated repositories merely because their build commands look similar.

The resulting placement model normally has three choices:

  • Shared build pool: low-sensitivity work from the same trust domain.
  • Segmented business pool: projects with different business boundaries but similar operational risk.
  • Dedicated release pool: signing, distribution, and production release work.

A dedicated host does not automatically create a secure system. It still needs protected routing, credential controls, cleanup, monitoring, and recovery validation.

Runner scope and route controls

Runner scope determines who can see and use a Runner, while tags determine which jobs request it. GitLab documents project, group, and instance Runner scopes in its Runner scope documentation.

The practical difference is accountability:

  • A project Runner gives the narrowest administrative boundary and is easier to review for a sensitive release project.
  • A group Runner supports shared infrastructure across a controlled portfolio, but the group membership and project inheritance must be reviewed.
  • An instance Runner offers broad reuse and central management, but it creates the largest blast radius if routing or credentials are misconfigured.

Use the narrowest scope that still meets the capacity requirement. A high-sensitivity signing Runner should not be instance-wide merely because central administration is convenient.

Route controls that must be tested

Runner tags, protected Runners, and protected branches work together, but each controls a different part of the route. Tags express job intent. Protection limits where sensitive jobs may run or which protected pipeline context may use them. None of these controls should be presented as a replacement for host isolation.

Check the configuration against the current GitLab Runner tag and Protected Runner documentation:

  • Use explicit tags for build, test, signing, and release classes.
  • Disable or reject untagged jobs where an untagged job could reach a sensitive node.
  • Bind release tags to a protected Runner.
  • Restrict release jobs to protected branches or tags.
  • Review who can create, edit, or trigger jobs that request the protected tag.
  • Test both the intended route and an unauthorized route.

The positive test should prove that an approved release pipeline reaches the release Runner. The negative test should prove that a merge request, unprotected branch, unrelated project, or manually altered job cannot reach it.

Can Runner tags and protected branches replace host isolation? No. They reduce accidental routing and unauthorized pipeline access, but they do not erase files, processes, caches, credentials, or network access left by an earlier job. Treat routing controls as one layer in the design, not as physical or host-level isolation.

Identity and signing asset separation

A GitLab Runner authentication token, repository credential, Apple signing certificate, Provisioning Profile, Keychain, and App Store Connect credential are separate assets. They should not share one permission layer or one unrestricted lifecycle.

GitLab documents risks around Runner authentication tokens in its Runner token security guidance. The token identifies the Runner connection; it should not be treated as a release credential or as permission to access every project.

A safer mapping looks like this:

Asset Build Runner Signing Runner Release control
Runner authentication token Limited to its assigned scope Separate protected Runner token Rotate after ownership or host changes
Repository access Minimum project or group scope Only required release repositories Audit use in pipeline logs
Signing certificate Not persistent where possible Stored only for approved signing flow Restrict to protected jobs
Provisioning Profile Not shared across unrelated trust domains Matched to the approved app and identity Validate before release
Temporary Keychain Created for the task when possible Created and removed under controlled steps Confirm deletion and lock state
App Store Connect credential Not available to compile-only jobs Available only to release jobs Review protected variable scope

GitLab’s CI/CD variable protection documentation explains how protected variables limit exposure to protected branches or tags. That control is valuable, but a protected variable can still be exposed if an authorized job runs on a host where another process or later task can read the result.

For release jobs, add protected environment controls and document who can deploy to each environment. GitLab’s protected environment documentation provides the relevant model.

Does an iOS signing task need its own GitLab Runner? It should use a dedicated protected Runner when the task has production release authority, handles restricted signing material, accepts code from different trust domains, or requires a stronger audit boundary than ordinary compilation. A same-domain internal test-signing job may use a segmented node only after the credential and residue tests pass.

Xcode 27 must also be treated as a toolchain condition, not as a reason to assume compatibility. Check the required macOS version and supported hardware against Apple’s official Xcode system requirements before assigning a Mac to the pool.

Workspace residue and recovery evidence

A cleanup script is useful, but it is not equivalent to a new host. A later job may read files before cleanup runs, inspect a cache that the script missed, or access a process and temporary credential created by the previous task.

Inspect at least these locations and states:

  • Repository checkout and generated source files.
  • DerivedData and other compiler output.
  • Dependency caches and package-manager downloads.
  • Temporary Keychains and signing profiles.
  • Build archives, logs, test reports, and export packages.
  • Shell history, environment files, process lists, and temporary directories.
  • Accounts, SSH agents, and background services created by jobs.

How should a Shell executor stop one project from reading another project's files? First, avoid placing unrelated trust domains on the same host. Then use separate service accounts or dedicated hosts where the risk requires it, isolate work directories, remove task credentials after use, and perform a residue scan after every representative job. File deletion alone does not prove isolation if the job can access shared caches, processes, or host-level services.

Use a repeatable recovery test:

  • Run a build that creates identifiable source, credential, cache, and archive markers.
  • Finish the job and execute the approved cleanup process.
  • Scan expected workspace, cache, Keychain, process, and log locations.
  • Run a second job under a different project identity.
  • Confirm that the second job cannot find the markers.
  • Reboot or reset the node according to the operating model.
  • Repeat the scan and record the resulting baseline.

A failed scan has a clear consequence: the node must remain outside the shared pool until the residue is removed or the node is reclassified as dedicated. Do not downgrade the finding because the file appears unlikely to contain secrets.

A cleanup log is evidence that a command ran. It is not evidence that the host returned to a trusted baseline.

Capacity, queue pressure, and recovery

Isolation changes capacity economics. Separating release work from general builds reduces the amount of idle capacity that can be reused, while putting every task on one shared Runner increases the security blast radius and can block release work behind ordinary builds.

Track operational measures instead of selecting a concurrency value from a generic recommendation:

  • Queue time by Runner class.
  • Build duration by project and toolchain.
  • Retry rate and failure cause.
  • Release-window demand.
  • Time required to reset or replace a node.
  • Number of jobs that require signing credentials.
  • Recovery time when a Runner becomes unavailable.

The GitLab Runner fleet planning guide supports a fleet-based planning approach. Use real project replays with the intended Xcode 27 toolchain, dependency setup, signing flow, and cleanup process. Do not use an isolated benchmark to claim that a fixed concurrency level will work for every iOS portfolio.

A practical fleet structure is:

  • Normal build capacity: shared only by projects in the same approved trust domain.
  • Sensitive release capacity: dedicated, protected, and monitored.
  • Temporary expansion capacity: added for a controlled migration, release window, or queue spike, then removed or reset.

Avoid making one dedicated Runner the only path to production. A secure design that cannot recover from host failure is still an operational risk. Recovery evidence should show how the Runner is replaced, how credentials are revoked, how the registration token is rotated, and how pending releases are rerouted.

For teams testing a remote Mac before committing to a larger fleet, the KuzCloud console can be used as the starting point for an isolated environment review. Procurement should compare the resulting reset process, queue behavior, credential handling, and operational ownership rather than comparing hardware rental and purchase prices alone.

Five-step deployment and acceptance sequence

Use this sequence before admitting a new project to a shared Mac Runner pool.

Define the trust domain

Record source sensitivity, contributor model, branch protection, release authority, and data classification for every project. Assign each task to shared, segmented, or dedicated capacity.

Evidence: approved project–task–asset matrix.
Failure consequence: the project remains unassigned and cannot use the shared pool.

Define Runner scope and route

Choose project, group, or instance scope. Apply explicit tags. Disable unsafe untagged execution. Bind signing and release tags to protected Runners and protected pipeline contexts.

Evidence: route configuration plus approved and unauthorized pipeline results.
Failure consequence: sensitive jobs stay off the node until the route is corrected.

Map credentials to tasks

Separate Runner authentication tokens, repository credentials, signing assets, Keychain data, and release credentials. Configure protected variables and protected environments only for the jobs that need them.

Evidence: variable scope review, Keychain lifecycle record, token rotation record, and failed unauthorized-access test.
Failure consequence: release credentials are removed from the node or the node is dedicated.

Prove cleanup and baseline recovery

Run representative builds that create source, cache, archive, log, and credential markers. Scan after the job, after reset, and under a different project identity.

Evidence: residue scan, reset record, and baseline comparison.
Failure consequence: the node is quarantined, reclassified, or rebuilt.

Replay capacity and failure

Replay real projects with the required Xcode 27 and dependency setup. Record queue behavior, build completion, retry causes, release-window demand, and replacement steps.

Evidence: build logs, queue records, failure recovery test, and backup routing plan.
Failure consequence: reduce the shared scope, add isolated capacity, or postpone onboarding.

Joint release scorecard

A shared Mac Runner should pass only when all critical controls have evidence. The following checklist is designed for an architecture review or procurement acceptance meeting.

  • [ ] Every project has an assigned trust domain.
  • [ ] Compile, test, signing, and release tasks have separate risk classifications.
  • [ ] Runner scope matches the smallest practical administrative boundary.
  • [ ] Sensitive jobs use explicit protected tags.
  • [ ] Untagged jobs cannot reach sensitive capacity.
  • [ ] Protected branches or tags are connected to the release route.
  • [ ] An unauthorized project and pipeline have failed to reach the protected Runner.
  • [ ] Runner authentication tokens are documented and rotated under a defined event.
  • [ ] Repository access is narrower than the host administrator boundary where possible.
  • [ ] Signing certificates and Provisioning Profiles are absent from compile-only nodes.
  • [ ] Keychain creation, use, lock, and deletion are recorded.
  • [ ] Protected variables and protected environments have named owners.
  • [ ] DerivedData, dependency caches, archives, logs, and temporary credentials have been scanned.
  • [ ] A second project cannot recover markers from the previous task.
  • [ ] The node reset process has been tested rather than described only in policy.
  • [ ] Xcode 27 and the required macOS conditions have been validated against Apple’s requirements.
  • [ ] Queue, build duration, retry, release-window, and recovery data come from representative projects.
  • [ ] A failed host has a documented replacement and credential-revocation path.
  • [ ] Procurement has chosen shared, dedicated, or mixed capacity based on evidence.

A failed control should lead to a specific action: remediate, narrow the Runner scope, move the task to a dedicated node, or pause onboarding. “The pipeline normally works” is not an isolation result.

Choosing shared, dedicated, or mixed Mac capacity

A fully shared model is suitable only when projects have comparable trust, contributor, credential, and release profiles. A fully dedicated model provides a stronger boundary but can leave capacity idle and increase operational ownership.

For most multi-team enterprises, a mixed model is the more defensible starting point:

  • Shared nodes handle low-sensitivity compilation and tests inside an approved domain.
  • Segmented nodes handle teams that need stronger separation but do not hold production release authority.
  • Dedicated protected nodes handle signing and release.
  • Temporary remote Mac capacity supports toolchain validation, migration, and recovery testing without forcing an immediate fleet-wide purchase.

If an external operator or remote Mac provider is being evaluated, verify how access, resets, host ownership, logging, and credential removal work before putting signing assets on the node. The KuzCloud support documentation can be used to confirm the operating workflow during a pilot, while the final decision should remain tied to the acceptance evidence above.

Buying Macs may be the better fit for long-lived, predictable workloads that require physical peripherals, local network access, or direct hardware custody. Renting remote Macs is more useful when the team needs a temporary validation node, flexible capacity, or a controlled way to test a new GitLab Runner and Xcode 27 workflow before expanding capital inventory.

A locally purchased Mac pool can create hidden work in hardware staging, replacement, patching, remote access, spare capacity, and secure disposal. A remote rental model does not remove those concerns; it shifts the review toward provider access, reset guarantees, network boundaries, and operational evidence. The right choice depends on the controls that the enterprise can actually verify.

Once the trust matrix and route tests are complete, a focused remote Mac pilot is a sensible next step: validate the GitLab Runner registration, Xcode 27 build, signing flow, cleanup scan, and host-replacement procedure on an isolated node. If those tests pass, the measured queue and release data can determine whether to expand into a shared build pool, a dedicated release pool, or a mixed Mac fleet through the appropriate KuzCloud Mac rental options.

Run Isolated macOS Builds with KuzCloud

Deploy a dedicated Mac for enterprise build workloads and keep teams, credentials, and workspaces separated.

Choose the capacity and region that fit your pipeline without purchasing or maintaining on-site Mac hardware.