How to Automate Unity iOS Builds with GitHub Actions

GitHub Actions is the most flexible way to build Unity iOS games without a Mac — and the most work. Here's the pipeline shape, plus the failures that eat the most time.

The pipeline shape

A working Unity iOS pipeline has two jobs, and splitting them matters for cost:

1. Build (Linux runner) — install Unity, activate the licence, export the Xcode project. Linux minutes are far cheaper than macOS minutes, and this is the long step.
2. Ship (macOS runner) — import signing material, archive with Xcode, export the IPA, upload to App Store Connect.

Running everything on macOS works but wastes money: macOS minutes are billed at a large multiple of Linux minutes, and the Unity compile is the slowest part.

What you need as repository secrets

• UNITY_SERIAL, UNITY_EMAIL, UNITY_PASSWORD — all three. Unity Personal serials work.
• Your distribution certificate as a base64-encoded .p12, plus its password.
• Your App Store provisioning profile, base64-encoded.
• App Store Connect API key (.p8 base64), Key ID and Issuer ID.

The failures that will cost you a day each

Runner disk space

The Unity iOS build image is large, and GitHub's Linux runners ship with limited free space plus a lot of preinstalled tooling. Builds fail with no space left on device partway through unpacking. The fix is to delete unused toolchains (dotnet, Android SDK, GHC, CodeQL) and prune Docker images before the build step.

Unity licence activation

Headless activation fails silently in confusing ways if the serial is missing — the log reports "0 entitlement groups" and the build dies much later with a licence error. Supply serial, email and password; don't rely on email/password alone.

Code signing on the runner

Three specific traps:

• The keychain auto-locks after 5 minutes. If your archive compiles for longer than that before signing, codesign hangs forever waiting for a GUI prompt that can't exist — the job burns to its timeout. Disable the auto-lock with security set-keychain-settings.
• Multiple certificates confuse automatic selection. If your team has more than one distribution certificate, tooling can pick one whose private key isn't on the runner. Pin an explicit certificate and profile.
• Frameworks reject profiles. Assign the profile to the app target only, never to UnityFramework.

Artifact permissions

upload-artifact does not preserve the executable bit. Unity's Xcode project runs helper binaries during the archive, so they fail with Permission denied after a round trip. Tar the build output before uploading and untar it on the macOS job — a tar preserves file modes.

Apple's moving SDK floor

Apple periodically raises the minimum SDK. Runners default to an older Xcode even when newer versions are installed, so uploads get rejected. Select the newest installed Xcode explicitly rather than trusting the default.

Is it worth building yourself?

If you enjoy infrastructure and want total control, yes — GitHub Actions is powerful and can be nearly free at low volume.

If you'd rather ship your game, the trade is stark: the pipeline above is a few hundred lines of YAML plus the debugging cycles that come with it, and every failure costs 15–25 minutes of build time to discover. MacFree drives GitHub Actions for you — it generates the workflow, creates and pins the signing material, and handles every issue listed above — from a button inside the Unity Editor.

Frequently asked questions