local-archive-export-upload · diff
git:20260914.8e6fc99 to git:20261114.5463d93
5 added, 0 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: local-archive-export-upload
description: 'Use when a build must reach TestFlight without Xcode Cloud (quota, outage, CI not wired yet), or when a local `xcodebuild archive` / `-exportArchive -exportOptionsPlist` / `xcrun altool --upload-package` command fails — `ExportOptions.plist` keys (`method`, `destination`, `teamID`, `manageAppVersionAndBuildNumber`), `-authenticationKeyPath` vs `-allowProvisioningUpdates`, `CFBundleVersion` colliding with Xcode Cloud''s counter. Temporary fallback for xcode-cloud-single-track-ci; does NOT cover ASC operations after upload → asc-api-automation, nor `notarytool` notarization → apple-skills:guide-macos-spm-packaging.'
allowed-tools: Bash(xcodebuild archive *)
---
# Local Archive, Export, Upload
The manual escape hatch for getting a build to TestFlight when Xcode Cloud's
**Main CI** workflow (→ `xcode-cloud-single-track-ci`) can't run — quota
exhausted, an outage, or CI not wired up yet. Same three Apple CLIs Xcode
Cloud uses under the hood — `xcodebuild archive`, `-exportArchive`, upload —
driven by hand instead of Apple's managed runner.
## When to invoke
- Xcode Cloud can't run but a build must reach internal TestFlight today.
- Writing or debugging a local archive/export/upload script or one-off command.
- Diagnosing an `ExportOptions.plist` / signing / build-number failure.
- Asked "how do I ship a build without Xcode Cloud" or "what does
`-exportOptionsPlist` need".
## Scope
Owns: the local three-step pipeline (archive → export → upload) and its
signing/export-key semantics. Does NOT own:
- ASC operations once the build exists (TestFlight groups, what's-new,
submission) → `asc-api-automation`.
- What has to be true for the build to *pass* review →
`app-store-review-rejections`.
- `.p8` / API-key storage → `build-time-secret-injection` +
`apple-public-repo-security`.
- Restoring Xcode Cloud once quota returns — this is a **temporary
substitute**, not a parallel permanent CI track.
## Pipeline
| Step | Command | Notes |
|---|---|---|
| 1. Archive | `xcodebuild archive -scheme <Scheme> -destination 'generic/platform=iOS' -archivePath build/App.xcarchive` | `-destination` picks the platform; a `generic/platform=...` destination (not a specific simulator/device) is what produces an archivable, distributable build. |
| 2. Export | `xcodebuild -exportArchive -archivePath build/App.xcarchive -exportPath build/export -exportOptionsPlist ExportOptions.plist` | Requires `-archivePath` + `-exportOptionsPlist`; `-exportPath` only needed when the plist's `destination` is `export` (see below). |
| 3. Upload | `xcrun altool --upload-package build/export/App.ipa --api-key <keyID> --api-issuer <issuerID> --wait` | `--api-key` / `--api-issuer` are the spelling `altool --help`'s own example uses; add `--wait` to block until Apple finishes processing instead of polling separately. Or fold into step 2 — see "One-step vs two-step" below. |
## Signing: two non-interactive paths
`xcodebuild -help` documents two credential sources for `-allowProvisioningUpdates`:
an account added in Xcode's Accounts settings, or an App Store Connect authentication
key passed via the `-authenticationKey*` trio. Both paths below therefore pass the flag
(needed on a script/cron path, not just CI):
| Path | Flags | Use when |
|---|---|---|
| Automatic signing via your Xcode account | `-allowProvisioningUpdates` (+ `-allowProvisioningDeviceRegistration` if a new device needs registering) | Run on your own dev Mac with an account added in Xcode's Accounts settings; xcodebuild creates/updates profiles and certs as needed. |
| API-key signing, no Apple ID session | `-allowProvisioningUpdates -authenticationKeyPath <p8> -authenticationKeyID <id> -authenticationKeyIssuerID <issuer>` | Unattended/scripted runs — reuse the same ASC API key from `asc-api-automation` / `build-time-secret-injection`, no Xcode account needed. |
+ Two signing failures that look like credential problems but are keychain state (observed on one machine, 2026-10, Xcode version not recorded; not found in Apple's docs):
+
+ - **Export signs locally instead of cloud-signing.** With automatic signing, `-exportArchive` was seen to use cloud-managed distribution signing only when no Apple Distribution certificate was in the keychain search list; a stale local one silently took over. Check `security find-identity -v -p codesigning` before blaming the key or profile.
+ - **`errSecInternalComponent` while signing** came from a locked login keychain, not lost keys: `security show-keychain-info ~/Library/Keychains/login.keychain-db` answers "Unable to obtain authorization". Unlock it (`security unlock-keychain`) in the unattended job before `xcodebuild`.
+
## ExportOptions.plist: the common shape
The full key set is printed by `xcodebuild -help` under "Available keys for
-exportOptionsPlist" (18 keys on Xcode 26.5, covering thinning, manifests, on-demand
resources). For a plain "ship to TestFlight" export, six keys are load-bearing
(cross-checked against the key list in `xcodebuild -help`):
```xml
<key>destination</key> <string>export</string> <!-- or "upload" -->
<key>method</key> <string>app-store-connect</string>
<key>manageAppVersionAndBuildNumber</key> <false/>
<key>signingStyle</key> <string>automatic</string>
<key>teamID</key> <string>ABCDE12345</string>
<key>uploadSymbols</key> <true/>
```
- **`method: app-store-connect`** — the current name; `app-store` still works
but Xcode 26.5's `xcodebuild -help` already marks it "deprecated: use
app-store-connect" (the exact Xcode version the rename landed in is
unconfirmed).
- **`manageAppVersionAndBuildNumber: false`** — defaults to `YES` (Xcode bumps
the build number for you on export); set `false` when your own tooling
controls `CFBundleVersion` — see build-number coordination below.
- **`teamID`** — omit to inherit the archive's signing team; set explicitly
when a machine/CI identity could resolve ambiguously.
### One-step vs two-step upload — pick two-step on purpose
| `destination` | Artifact | Gate before upload | Use when |
|---|---|---|---|
| `export` | `.ipa`/`.pkg` written to `-exportPath` | Your own `--dry-run`/`--i-am-sure`-style flag on a separate upload command | Default |
| `upload` | None — xcodebuild uploads directly to Apple, no local artifact, no separate `altool` call | None — the network push happens the instant `-exportArchive` runs | Deliberate one-shot only |
Prefer `destination: export` + a separate, deliberately-gated upload command
so archive/export stay safe to run freely and only upload needs a human's
explicit go-ahead.
## Upload tool
`xcrun altool --help` (Xcode 26.5) lists `--upload-package <file>` first among
App-Upload commands and uses it in its own canonical example; the older
`--upload-app -f <file>` still works but isn't the tool's own example anymore.
altool searches fixed directories for `AuthKey_<keyID>.p8` (`./private_keys`,
`~/private_keys`, `~/.private_keys`, `~/.appstoreconnect/private_keys`, or
`$API_PRIVATE_KEYS_DIR`) — stage a per-run symlink into one of these if your
key lives in a gitignored `secrets/` dir, rather than moving the real file.
**`notarytool`** is not this path — it handles Developer-ID notarization
(outside-the-App-Store distribution), unrelated to TestFlight/App Store
uploads. The ASC API's Build Uploads path also works (see
`references/official-docs.md`), but this skill still defaults to `altool`.
For the other upload paths (Xcode Cloud, Xcode Organizer, Transporter), read
`references/official-docs.md`.
## Build-number coordination with Xcode Cloud
Per `xcode-cloud-single-track-ci`, Xcode Cloud assigns its own sequential
`CI_BUILD_NUMBER` per build, independent of whatever's in the repo. A local
build needs a `CFBundleVersion` that will never collide with — or fall below —
that counter:
- Use a high-resolution timestamp (`YYYYMMDDHHmm`) rather than a small
hand-incremented integer — it can't collide with Xcode Cloud's small
sequential counter, and TestFlight rejects a duplicate `CFBundleVersion` for
the same `CFBundleShortVersionString`.
- macOS additionally requires build numbers to strictly increase *across*
versions — if a local timestamp-based number ends up higher than Xcode
Cloud's next assigned number, fix it once on the ASC side (Xcode Cloud →
Settings → Build Number → Edit), the same fix `xcode-cloud-single-track-ci`
documents for its "existing Mac app" exception.
- Set `manageAppVersionAndBuildNumber: false` (above) so Xcode's export-time
bump doesn't fight your chosen number.
## Rationale
Every flag and key here is verifiable straight from Apple's own CLI (`man
xcodebuild`, `xcodebuild -help`, `xcrun altool --help`) — no fastlane, no
third-party packaging tool, consistent with this catalog's no-Homebrew /
Apple-native-first baseline (`asc-api-automation` makes the same call for ASC
REST automation). Provenance for each claim (doc-verified vs practice-observed)
is in `references/evidence.md`.
## Deviation considerations
- **Xcode Cloud is back / never was the bottleneck** — retire the local path;
don't run it as a second permanent track (`xcode-cloud-single-track-ci`'s
single-track rule).
- **Frequent local ships** — the "temporary substitute" framing breaks down;
invest in restoring/expanding Xcode Cloud capacity instead of hardening
this manual path further.
## Common Mistakes
1. Pre-`touch`ing `ExportOptions.plist` before writing it with `PlistBuddy`.
2. Using `destination: upload` as the default — loses the archive-only dry run.
3. Leaving `method: app-store` (deprecated form) in an old plist.
4. Hand-incrementing a small `CFBundleVersion` locally — collides with Xcode
Cloud's own counter.
5. Reaching for `xcrun notarytool` for a TestFlight upload — it's for
Developer-ID notarization, a different distribution path entirely.
6. Forgetting `ITSAppUsesNonExemptEncryption` on a new app — the build is
marked Missing Compliance until the export-compliance questions are answered
in ASC or via `PATCH /v1/builds/{id}` (`usesNonExemptEncryption`).
## Review Checklist
- [ ] Archive uses a `generic/platform=...` destination, not a specific
simulator/device.
- [ ] Export uses `method: app-store-connect` (not the deprecated `app-store`).
- [ ] Signing passes `-allowProvisioningUpdates` on every path, with a
deliberate credential source: the Xcode Accounts login (your dev Mac) or
the `-authenticationKeyPath` trio (unattended).
- [ ] `destination: export` + a separate gated upload step, unless a one-step
`upload` is a deliberate choice.
- [ ] `CFBundleVersion` source can't collide with Xcode Cloud's `CI_BUILD_NUMBER`.
- [ ] `ITSAppUsesNonExemptEncryption` set in Info.plist (or export-compliance
is otherwise answered).
- [ ] `.p8` staged only via a per-run symlink into an altool-searched
directory, never committed or left behind after the run.
## Related skills
- `xcode-cloud-single-track-ci` — the primary CI path this substitutes for;
restore it once quota/outage clears.
- `asc-api-automation` — TestFlight/App Store operations once the build lands in ASC.
- `app-store-review-rejections` — its export-compliance row (an ASC upload
step, not a Guideline number) and what has to be true for review to pass.
- `apple-skills:guide-macos-spm-packaging` (aggregated external) — Developer-ID
signing / `notarytool` notarization for outside-the-App-Store distribution.
- `build-time-secret-injection` / `apple-public-repo-security` — where the
`.p8` and its issuer/key IDs live and how leaks are prevented.
- `storekit2-iap-defaults` — this pipeline is how a build carrying that
skill's IAP code reaches TestFlight.
- Official sources: when verifying or updating a factual or version-sensitive claim, read `references/official-docs.md`.