A Bazel remote cache has two distinct parts: an action cache and a content-addressable store, as described in the Bazel remote caching documentation. First make the iOS build reproducible on the remote Mac; then add the cache and prove that another Mac reads the result. A cache hit is not remote execution, and neither one replaces Xcode, packaging, or code-signing checks.
This guide is for developers maintaining iOS build rules with Bazel and for build or DevOps engineers responsible for shared CI infrastructure.
If the build works only on one workstation, start with the toolchain baseline rather than debugging cache settings.
If you need a general remote Mac environment overview, see remote Mac environment options.
00Establish a repeatable build before changing cache settings
A remote cache can reuse only results Bazel considers eligible for the configured action and its inputs. It cannot repair a build that fails because the remote Mac selects a different Xcode installation, lacks an expected SDK, or receives different build flags. A cache miss is therefore hard to diagnose until the uncached build itself is reliable.
Start on the Mac where the project already builds successfully, or on the remote Mac if that is the intended reference machine. Build the project’s real iOS target, run its relevant tests, and preserve the logs. Record the exact repository revision and the project’s locked dependencies alongside the build result. Do not infer tool compatibility from a version number alone: use the project’s lockfiles and the official documentation for the Bazel and Apple platform rules it has selected.
| Baseline item | Record and compare | Why it matters |
|---|---|---|
| Bazel and platform rules | The versions or revisions pinned by the project, including rules_apple and rules_swift |
A changed rule set can change action inputs or how Apple tools are invoked. Check the official rules_apple repository and the project’s own pinned references. |
| Apple toolchain | Selected Xcode, command-line tools, and the SDK used by the target | The name of an installed Xcode application alone does not prove that the shell selects it. Apple documents the relevant Xcode command-line tools and their installation and selection context. |
| Build definition | Target, configuration, platform options, and relevant .bazelrc settings |
The same source can produce different actions when build options differ. |
| Environment inputs | Variables and tool paths that the build actually uses | Undeclared or inconsistent inputs can produce unstable results or prevent useful cache reuse. |
| Evidence | Build and test logs, generated artifact, and a way to identify that artifact | A green exit status alone does not establish that the expected target or output was produced. |
On the reference Mac, confirm the selected Apple tools from the same shell context that will run Bazel:
xcode-select -p
xcodebuild -version
xcrun --sdk iphoneos --show-sdk-version
These commands provide a record of the selected developer directory, Xcode version, and iOS SDK version. Apple’s command-line tool reference describes the available command-line interface. Save the output with the build log; avoid copying a result from a different login session or shell configuration.
Next, run the project’s ordinary Bazel build and test commands without changing the cache policy. Use the actual targets maintained by the project, not sample target names from a guide. Record whether the build, tests, and expected artifact all complete. If the remote Mac cannot reproduce this baseline, fix that first. Adding shared caching at this stage can hide the source of differences or make a previous result appear to validate a broken environment.
01Align the remote Mac with the project’s Apple toolchain
A remote Mac is still a Mac build environment, not a generic Linux worker with an Apple-themed endpoint. Bazel can coordinate actions, but Xcode and Apple SDK availability still matter for the project’s Apple platform build. Keep the toolchain comparison explicit before asking a second machine to share results.
| Check on each Mac | Evidence to capture | Response to a mismatch |
|---|---|---|
| Selected developer directory | Output of xcode-select -p from the build shell |
Select the project-approved Xcode installation, then repeat the baseline build. |
| Xcode and SDK | Output of xcodebuild -version and the relevant xcrun SDK query |
Confirm the project supports the selected toolchain; do not assume an SDK is interchangeable because both machines build iOS targets. |
| Bazel configuration | Relevant .bazelrc files, command-line options, and target |
Make the intended configuration visible to both machines and CI. |
| Environment | Required variables and executable search paths | Identify inputs the build relies on, then make them consistent and declared where the project’s build rules require it. |
| Repository state | Revision, generated files, and dependency lock state | Ensure both builds test the same source and dependency state. |
If Xcode command-line tools are missing or the active selection is wrong, follow Apple’s installation guidance and rerun the baseline. Do not treat a failed toolchain check as a cache failure. Keep a short environment record beside the build logs so that a future failure can be compared against the known-good state.
Before configuring shared access, separate the build jobs by trust level. A developer build may need read access to shared results, while only a controlled CI identity may be allowed to upload them. Keep credentials out of repository files, command history, and logs. Use the project’s supported secret-management approach, restrict credentials to the required endpoint and operations, and review the effective permissions before enabling writes.
02Decide what belongs in the cache and what does not
Bazel’s remote cache and remote execution solve related but different problems. A cache stores and serves eligible action results; remote execution schedules eligible actions to run on remote workers. The Bazel remote execution overview describes that separate capability. Configuring a cache does not, by itself, move compilation to another machine.
Keep these acceptance claims distinct:
- Cache read: Bazel reports that an eligible action result was obtained from the configured remote cache.
- Cache write: The build identity is authorized to upload eligible results, and the evidence shows an upload occurred.
- Remote action execution: The configured execution service reports that an action ran remotely.
- Mac-local execution: The action ran on the remote Mac that is being used as the build host, rather than on a separate execution worker.
- Packaging and signing: The intended application artifact exists and passes the project’s release checks.
The project’s use of rules_apple matters when deciding which actions can run in which environment. Review the official rules_apple guidance for the project’s selected rules, then validate any remote-execution assumptions against its locked versions. Do not claim Apple toolchain actions are remotely executable merely because ordinary build actions are cached. Confirm the behavior in the actual project and the execution environment.
Signing is a separate security and release boundary. Keep certificates, provisioning material, and signing credentials out of general cache permissions unless the project has explicitly designed and reviewed a safe process for them. Check the final application and its signature on the intended Mac. Apple’s guidance on creating distribution-signed code explains the signing workflow; use the relevant project and platform process rather than treating a successful Bazel action as release approval.
03Configure Bazel iOS remote cache with explicit permissions
Once both the reference Mac and the remote Mac can reproduce the baseline, choose the cache endpoint and document who may read or write. Use the configuration entry point already maintained by the project, such as its shared .bazelrc, and verify the exact options against the Bazel remote cache configuration documentation.
A configuration sketch can show the intended endpoint without embedding credentials:
build --remote_cache=<approved-cache-endpoint>
Replace the placeholder with the endpoint approved for the team. This line alone does not establish authentication, write access, or cache safety. Follow the endpoint’s supported authentication method and Bazel’s documented settings. Keep secrets in the approved credential mechanism, not in a checked-in configuration file. Avoid turning on broad write access simply to make an initial test easier.
Set permissions according to the task:
- Give ordinary developer builds only the access they need. If they only need to consume known-good results, do not grant upload permissions by default.
- Use a controlled CI identity for approved writes. Review which workflows can obtain that identity and whether untrusted changes can trigger them.
- Exclude targets or actions that the project cannot safely share, such as outputs involving secret or machine-specific inputs. Make the exclusion deliberate and document the reason.
- Confirm that endpoint credentials are not printed in build logs, shell tracing, or diagnostic bundles.
A write-enabled test should have observable evidence. Run the known target, preserve the Bazel output, and verify that Bazel reports the intended remote cache interaction. A successful build with no read or upload evidence proves only that a build completed; it does not prove that the cache was configured correctly.
04Prove cross-Mac cache reuse with the same action
Use a controlled test that changes the machine, not the build inputs. On the first Mac, build the selected target with the approved cache configuration and confirm the expected write behavior. Then use the second Mac with the same repository state, toolchain selection, Bazel configuration, target, and build options. Preserve both logs.
The comparison should keep these inputs fixed:
- The same source revision and dependency state.
- The same Bazel and Apple platform rules selected by the project.
- The same Xcode selection and SDK.
- The same target and build options.
- The same declared environment inputs and cache endpoint.
The Bazel cache troubleshooting guide is useful when the expected read does not appear. Compare its diagnostics with the actual Bazel output rather than relying on elapsed build time or a green status. A faster build may have skipped work for another reason; a successful build may have run locally without reading the remote cache.
Use this decision path before widening access:
- If the first Mac’s log shows the expected upload and the second Mac’s log shows the expected remote read for the same action, then retain the configuration and repeat the check with the project’s relevant test target.
- If the build succeeds on both Macs but the second log does not show a remote read, then treat cross-machine reuse as unverified. Compare toolchain, options, environment, endpoint, credentials, and network access before changing cache policy.
- If the second Mac cannot reproduce the uncached baseline, then stop cache debugging and repair the toolchain or project environment first.
- If cache access fails because of permissions or endpoint availability, then preserve the failure logs and test the documented fallback before allowing the cache to become a release dependency.
Bazel provides controls for remote cache reads and uploads; use the options documented for the project’s selected Bazel version. Keep read and write behavior intentional. For example, a read-only validation can help isolate whether results are available without authorizing another machine to upload. Re-run the same test after each meaningful change so that a changed toolchain, target, or environment does not invalidate the comparison.
05Move from a verified test to CI in controlled stages
After the cross-Mac test passes, move the same reviewable configuration into CI. The CI job should use the intended source revision, Bazel settings, and Apple toolchain as the developer validation. Confirm which identity CI uses, what permissions it receives, and where its credentials come from. A developer’s successful cache read does not prove that CI has network access or the same authorization.
Begin with a limited workflow that records the build output and verifies the intended cache behavior. Then run the project’s relevant tests and inspect the generated iOS artifact. If a release build signs or packages the application, keep that as a separate validation stage with its own access controls and checks. The cache’s role is to reuse eligible results; it is not evidence that a release artifact is correctly signed.
Use this rollout checklist:
- [ ] The baseline build and tests succeed on the selected remote Mac without depending on a previous cache result.
- [ ] The selected Xcode, SDK, Bazel settings, rules, target, and relevant environment are recorded.
- [ ] Cache endpoint and authentication are configured through approved project mechanisms.
- [ ] Read and write permissions are assigned to the intended identities and reviewed.
- [ ] Bazel output provides evidence of the expected upload and cross-Mac read.
- [ ] A failed or unreachable cache has a documented fallback and visible logs.
- [ ] The produced iOS artifact and any signing or packaging stage are checked independently.
- [ ] No performance claim is made unless the team has measured the same workload under comparable conditions.
Do not announce a speedup based only on the first successful cache hit. Establish the team’s own baseline and compare equivalent builds with the same inputs. Record whether the improvement comes from cache reuse, changed build behavior, or another factor. If the cache is unavailable, the build should fail or fall back according to an explicit policy; silently treating an unverified run as a cache success weakens release evidence.
06Frequently asked questions
How should an iOS project start using a Bazel remote cache?
First make the project build and test reproducibly on the intended remote Mac without relying on a shared cache. Record the locked Bazel and Apple toolchain inputs, then configure an approved cache endpoint and explicit read and write permissions. Build on one Mac, confirm uploaded results in Bazel output, and test the same target from another Mac before enabling broader CI use.
How is remote caching different from remote execution in Bazel?
Remote caching lets a build reuse eligible action results that already exist in a shared cache. Remote execution schedules eligible actions to run on remote workers instead. A cache hit does not show that an action ran remotely, and successful remote execution does not prove that the expected cache was read. Verify each capability using its own configuration and execution evidence.
Why might the same Bazel target miss the cache on different Macs?
Compare the exact source revision, Bazel settings, selected Xcode and SDK, declared environment inputs, target, and build options first. Then check credentials, cache endpoint access, network reachability, and whether the first machine uploaded results. A build that succeeds on both Macs is not proof of a cache hit; confirm the cache-read evidence in Bazel output.
Should code signing and final iOS packaging run through remote execution?
Treat signing and release packaging as separate acceptance stages, not as a consequence of cache hits. Their requirements depend on the project’s Apple toolchain actions, signing assets, and execution environment. Follow the project’s rules_apple guidance, inspect the produced application, and verify its signature on the intended Mac before approving release. Keep signing credentials outside general-purpose cache write access.
A Linux build host can serve cross-platform work, but it cannot replace the Mac-side Xcode and Apple-toolchain checks required by this workflow. Buying and maintaining a dedicated Mac gives a team direct control over hardware and persistent access, but also means handling procurement, upkeep, and capacity planning. When the need is a testable, continuously available Mac build environment without committing to a purchase, NUKCLOUD remote Mac access is another option to evaluate. Review the available remote Mac plans against the project’s toolchain, access, and signing requirements before moving CI workloads.