A build fails because its runner cannot reach an internal package registry or firewall allowlist.
Fastest fix: if a Mac build needs direct intranet access or a static source IP, do not default to macOS larger runners. Verify their current network limits, then evaluate a self-hosted Mac with the required network path. Prefer hosted runners only when dependencies are publicly reachable or a tested intermediary works.
This runbook is for:
- IT leaders deciding how CI can reach private repositories, registries, and internal services.
- Platform engineers splitting iOS and macOS jobs between hosted and self-hosted Macs.
- Security and procurement teams weighing network control, operations, and workload placement.
Scenario 1: Your build only needs public resources
A hosted runner is worth evaluating when every build dependency is reachable from that runner and the workflow identity is allowed to use it. “Publicly reachable” and “authorized” are separate checks: an endpoint can be reachable from the internet while still requiring a valid token or restricted account.
Start with the actual workflow, not an architecture diagram. List source repositories, package registries, build services, signing dependencies, and artifact destinations. For each item, record the hostname, authentication method, and whether access depends on a corporate route, VPN, or trusted source address.
| Dependency | What to establish | Evidence to keep |
|---|---|---|
| Source repository | Is it reachable, and can this workflow identity read it? | Workflow permissions and checkout result |
| Package registry | Is the endpoint reachable from the runner, and is the credential scoped correctly? | Dependency manifest, install log, and registry access log |
| Build or test service | Does it accept the runner’s route and authentication method? | Successful request and service-side audit record |
| Artifact destination | Can the workflow publish only the intended output? | Upload result and destination permissions |
A GitHub-hosted runner can be a sensible starting point if this inventory shows no dependency on a private network path. That is not a blanket approval for every enterprise build. Confirm the runner’s access controls and the organization’s policies in the larger-runner access documentation.
A successful checkout does not prove that the rest of the build can reach private services. Check each dependency separately.
For example, a workflow may fetch source from an authorized repository and then fail when a build script requests an internal API. That is a network-path failure, not necessarily a repository permission problem. Capture the failing hostname and the service-side denial before changing runner types.
Scenario 2: Your build needs a private registry or internal service
First separate private access by location and direction. A private repository hosted on a service reachable from the runner may require authorization without requiring a corporate LAN route. A package registry available only through an internal address needs a network path as well as credentials.
Use this table to map the request before selecting a runner:
| Request path | Questions to answer | Decision signal |
|---|---|---|
| Runner to private package registry | Is the registry reachable from the runner? Which identity can download packages? | If network access depends on the corporate LAN, validate a route before approving hosted CI |
| Runner to internal API or secret service | Does the service accept the runner’s egress path? How is the workflow authenticated? | If it accepts only a corporate route or source allowlist, test a supported intermediary or self-hosted placement |
| Internal service to runner | Does the service need to initiate a connection back to the runner? | Confirm connection direction; do not assume an inbound path exists |
| Runner to artifact store | Is the store accessible through an approved endpoint? Can publishing be limited to the required workflow? | Validate both connectivity and write permissions |
GitHub’s documentation states that macOS larger runners do not provide static IP addresses or Azure private networking. Check the current GitHub-hosted runner reference before designing a firewall rule around either capability.
Run a test workflow against the real registry or service. A local test from a developer laptop proves only that the laptop has access. For CI acceptance, retain the workflow configuration, dependency list, runner logs, and corresponding registry or service access records. A timeout, DNS failure, and authorization denial point to different causes; do not “fix” all three by widening access.
Scenario 3: Your firewall requires a static source IP
If a firewall rule depends on a fixed source address, treat that as a hard requirement until the security owner approves another control. GitHub documents that macOS larger runners do not offer static IP addresses. Do not infer macOS support from a networking option documented for a different runner type.
| Requirement | macOS larger-runner implication | Next decision |
|---|---|---|
| Allow only a fixed runner source IP | The documented macOS larger-runner capability does not meet this requirement | Evaluate a network-controlled self-hosted Mac or another security-approved route |
| Allow access based on authenticated workflow identity | May be possible through a suitable service or gateway design | Verify identity claims, token scope, service policy, and audit evidence |
| Permit a stable corporate egress route | Requires proof that the selected runner path uses that route | Test the route and confirm it with network logs before relying on it |
Ask the firewall owner what the rule is protecting against. The requirement may be a genuine fixed-address control, a broad allowlist restriction, or a proxy for stronger identity and audit requirements. Those are not interchangeable. If identity-based access is acceptable, document the exception and have the security team approve it; do not quietly replace a network control in the workflow.
A self-hosted Mac can be placed on a network with a controlled route, but registration alone does not grant intranet access. Placement, routing, DNS, firewall policy, host configuration, and service authorization still decide whether the build can connect. The self-hosted runner communication requirements should inform the network review, alongside your own host and firewall logs.
A stable route is not host isolation. A runner that can reach an internal service can also expose that service to unsafe workflow code if permissions are too broad.
Scenario 4: A gateway or network overlay might mediate access
An intermediary can reduce direct exposure of an internal service, but it does not automatically solve runner compatibility, identity, or routing. Test one target service and one workflow before adopting the pattern across your build estate.
| Option | What it can address | What you must verify |
|---|---|---|
| API gateway with workflow identity | Service access authenticated through a gateway, where the documented method and target service fit | Whether the documented OIDC approach applies to your runner; token audience, claims, scope, and gateway logs |
| Network overlay | A controlled network path between participating systems, if the runner and service can use the documented setup | macOS runner applicability, route, DNS, key handling, peer access, and teardown |
| Azure private networking | Private networking for the runner types in its documented scope | Whether that scope explicitly includes your target macOS larger runner; do not assume it does |
GitHub documents an OIDC-based API gateway approach and a WireGuard network-overlay approach. Read each method’s prerequisites and applicability. General GitHub-hosted runner guidance is not proof that a method is supported for every macOS larger-runner configuration. The Azure private networking documentation also has a defined scope; confirm it directly before planning around it.
For each proposed route, record the target hostname, destination port, authentication mechanism, credential lifetime, egress path, and audit source. If you cannot verify one of these, mark the design as pending. A successful connection test alone is not a security approval.
Scenario 5: Your network path points to a self-hosted Mac
Choose a self-hosted Mac when your acceptance criteria require a host located in a controlled network environment or a route you manage. It may be the better fit for private dependencies and fixed-egress policies, but it shifts operational work to your team.
Before onboarding, confirm the host’s actual placement and route to every required service. Test DNS resolution, service ports, authentication, and failure visibility from a workflow running under the intended runner account. Keep the service-side records so you can distinguish a network failure from an expired credential or a rejected identity.
Plan for these costs and risks:
- Host operations: patching, Xcode and toolchain changes, disk recovery, monitoring, and capacity planning.
- Credential exposure: restrict secrets to the jobs that need them, rotate credentials, and avoid leaving broad tokens on a persistent host.
- Workflow trust: control which repositories, branches, and contributors can schedule jobs on the Mac. A self-hosted runner is not isolated merely because it is remote or privately connected.
- Recovery responsibility: document who restores the host and how the team verifies signing and build behavior after recovery.
Review the larger-runner management documentation alongside your host-control plan. Compare responsibilities, not just access: a hosted runner delegates some machine operations, while a self-hosted Mac gives your team more responsibility for its lifecycle and local security.
If you are also considering a remote Mac outside your own fleet, first define the required connection method, permitted network route, and geographic or organizational constraints. You can review MACCOME’s remote Mac options as an option to evaluate, but confirm the actual delivery path and limitations against your own acceptance criteria. Do not assume that remote access provides an intranet route or host isolation.
Scenario 6: Your pipeline can split public and private work
A mixed pipeline can keep publicly reachable build and test steps on a hosted runner while reserving private-network tasks for a runner with an approved route. This is useful only if the handoff between jobs is explicit. Define what artifact moves between them, which identity may read or publish it, and where signing occurs.
Use this acceptance list before approving the design:
- [ ] Inventory every source repository, package registry, API, secret service, and artifact destination used by the workflow.
- [ ] Mark each dependency as internet-reachable, organization-authorized, or reachable only through a corporate network path.
- [ ] For every private dependency, record the connection direction, hostname, port, authentication method, and required source-address policy.
- [ ] Check the current macOS larger-runner documentation for static IP, private networking, and any proposed intermediary. Record unsupported or unverified assumptions.
- [ ] Run a test workflow using the intended runner type and the actual dependency endpoints.
- [ ] Match workflow logs to network, gateway, registry, and service audit records.
- [ ] Verify that the artifact handoff preserves the required identity, access boundary, and signing controls.
- [ ] Record open acceptance items, the team responsible for each, and the fallback runner path if a test fails.
Do not split jobs until the artifact transfer and signing sequence have passed a real workflow test. A build that passes on one runner and signs on another can still fail because of missing files, different permissions, or an incorrect release boundary. Keep the split only when the workflow proves the handoff and the security team accepts the resulting access model.
The decision record should state the network hard constraints, who maintains each Mac, how credentials are protected, and which acceptance tests remain open. If a required path is not verified, keep that job off the proposed production runner.
Common questions
Can macOS larger runners download packages from a private registry?
They can use resources that the runner can reach and is authorized to access, but a package being private does not itself establish network connectivity. Distinguish a private repository hosted on an accessible service from a registry reachable only inside your corporate network. Test the exact workflow identity, registry endpoint, credentials, and access logs before treating the dependency as supported.
Can I allowlist a fixed IP for GitHub Actions macOS larger runners?
GitHub's documentation states that macOS larger runners do not provide static IP addresses. If your firewall requires a fixed source address, do not build an allowlist plan around an address you cannot rely on. Check whether the service can instead authorize a narrowly scoped identity or gateway path; otherwise evaluate a self-hosted Mac with a network path your organization controls.
Should enterprise iOS CI use a hosted or self-hosted Mac for intranet dependencies?
Choose based on the required network path, not the runner label. A hosted runner can suit builds whose dependencies are reachable through supported, tested routes. A self-hosted Mac may fit when it must sit on a corporate network or use a controlled egress address, but your team then owns host maintenance, credential protection, and workflow risk.
Can a gateway or network overlay connect a CI runner to an internal service?
Possibly, but treat each design as an integration to validate, not a universal runner feature. Confirm that the documented method applies to the macOS runner you plan to use, then test service reachability, workflow identity, credential scope, egress path, and audit records. If any of those checks remain unproven, keep the route out of production CI.
If your current setup relies on broad firewall exceptions, an unmanaged build host, or repeated manual network changes, those are operational costs to include in the comparison—not reasons to assume a hosted runner will solve private access. When a remote Mac could fit the verified workflow, compare the required connection path and responsibilities before choosing it. You can review MACCOME’s Mac mini options, then validate the network route and access boundaries with your own workflow before assigning production jobs.