Get your first iOS build pipeline running

If xcodes isn’t installed on the host, set it up using your team’s approved software installation process. To install a specific version, use a locally available Xcode installer obtained through legitimate channels and matching your project requirements. XCODE_VERSION and XCODE_XIP below refer to the verified version number and the installer’s absolute path, respectively. Don’t put interactive installation steps in unattended build jobs.

XCODE_APP should point to the actual path of the installed app. For CI, set DEVELOPER_DIR in the job environment where possible, rather than having jobs compete to change the global selection. If you need to switch the system-wide default toolchain, run sudo xcode-select --switch "$XCODE_APP/Contents/Developer", then verify it again with xcodebuild -version.

Launch the selected version of Xcode once and complete any required component setup. You can use a remote connection to access the graphical interface, then install the target runtime in Xcode’s component settings. Run xcrun simctl list devices available and choose a simulator that matches your test target. Launch it interactively once and wait for startup to finish before running a minimal test job. Archiving a device build and running simulator tests are separate steps; don’t mistake a missing runtime for an archive toolchain issue.

Log toolchain checks at the start of each CI job: include at least the Xcode version, SDK list, and commit ID. After changing Xcode, generate a new cache key and verify third-party dependencies, signing, and export. Changing only the runner label without checking the actual tool path won’t ensure a consistent build environment.

GitLab Runner: Check labels and executor together

Create a project runner in your project’s runner settings, get its authentication token, and assign the labels macos, arm64, and ios-archive. Temporarily set the instance URL and authentication token as GITLAB_URL and GITLAB_RUNNER_TOKEN, then register a shell executor under a dedicated build user. Remove the temporary token variable when you’re done.

Set IOS_WORKSPACE and IOS_SCHEME to the values used by your project, and complete the signing setup in the next section first. This example archives the app only; it doesn’t export or upload it. The seven-day artifact retention is just an example—adjust it to your team’s retention policy. Don’t put certificates, private keys, or temporary Keychains in artifacts.

GitHub Actions: One job per runner process

Follow the runner installation steps in your repository settings to get the software for macOS ARM64, then move into the extracted directory. Set REPOSITORY_URL to your repository URL and RUNNER_TOKEN to the token for this registration. Use the same labels in the runner configuration and workflow to avoid routing jobs to the wrong toolchain.

Set the tool path, workspace, and scheme in your repository variables first. This example uses manual triggering so you can validate the environment before automating it. Don’t expose a runner with signing credentials to untrusted external code. Each runner process takes one job at a time, while concurrency limits workflows in the same group; it doesn’t impose host-level resource limits.

Once everything checks out, use the supplied service script to keep the runner running, and make sure the service user matches the user you tested with manually. If you set up signing under one user but run the service as another, interactive builds may succeed while CI can’t find the certificate or provisioning profile.

Use a separate build Keychain for automation, with its password supplied through a protected CI secret. After importing the certificate, grant access only to the signing tools that need it; don’t allow every app to access the private key. The checks below confirm that the current user can see a valid signing identity. They don’t guarantee that the provisioning profile, export settings, and project configuration all match.

Provisioning profile locations can vary between Xcode versions, so use the path read by your current toolchain. After importing a profile, check its expiry date, app identifier, and signing type. If archiving succeeds but exporting fails, check the distribution method, team ID, and profile mapping in the export settings instead of repeatedly reinstalling Xcode.

If your team already uses fastlane match, stick with its existing encrypted certificate repository and access policy. During validation, use bundle exec fastlane match appstore --readonly to read existing signing assets without accidentally changing team certificates from the build host. Manage repository credentials, the decryption password, and the Keychain password separately. Expose production signing secrets only to protected branches or controlled manual jobs.

At the end of each job, remove temporary files and lock the temporary Keychain. Keep only the necessary error codes and step results in logs; never print private key contents, certificate passwords, registration tokens, or secret variable values. A dedicated physical machine provides resource isolation, but credentials within your project should still follow the principle of least privilege.

Run diskutil list and df -h to check capacity and mount points. Don’t erase or partition an unfamiliar disk. Create a cache directory that the build user can write to and test it with a small file. Once you’ve confirmed how the volume mounts after a restart, point your persistent runner to the new path.

Pause incoming jobs before migration and wait for any running archive or signing tasks to finish. DerivedData is a rebuildable cache, so generate it at the new location rather than copying an old cache that may still be in use. The example below uses an explicit -derivedDataPath; you don’t need to move the entire user directory to the extra volume.

Before running the commands, set BUILD_VOLUME to a confirmed writable mount point. CACHE_KEY should distinguish the repository, Xcode version, and build configuration. Use a unique ID for the current job as BUILD_ID so jobs don’t overwrite each other’s archives. Don’t share a writable DerivedData directory between parallel jobs.

Run one build without a cache first, then monitor cache hits and disk usage in subsequent jobs. Set separate retention policies for archives, simulator data, and dependency caches, and check that no job is using the files before deleting them. Store build artifacts separately in storage controlled by your team; host caches aren’t a backup. Export what you need before your rental term ends, and verify that your backup can be read.