Magic Deploy Setup

What you're filling in

When you click Magic Deploy in LingCode and choose App Store Connect (API key), you'll see four fields. Each comes from a different page on Apple's developer portals — this guide walks through them in the order LingCode shows them.

Before you start — one-time Apple setup

The four fields in Magic Deploy are the final piece. Several things have to already be true on the Apple side, or the upload will fail in ways the UI can't always explain clearly. Walk this checklist once, then you're done for the life of the project.

1. A paid Apple Developer Program membership

A free Apple ID can build and run on your own Mac but cannot upload to App Store Connect. Enroll at developer.apple.com/programs/enroll. It's $99/year for an individual; organizations need a D-U-N-S number and typically take 3–10 business days to be verified. Until your account status shows as Active on developer.apple.com/account, none of the steps below will work.

2. Xcode installed, not just Command Line Tools

LingCode Magic Deploy shells out to xcodebuild, which lives inside the full Xcode app — the standalone Command Line Tools bundle is not enough. Install Xcode from the Mac App Store or developer.apple.com/download, open it once to accept the license, then confirm in Terminal:

xcode-select -p
# should print: /Applications/Xcode.app/Contents/Developer

If it prints /Library/Developer/CommandLineTools instead, point it at Xcode:

sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

3. Signed in to Xcode with your developer account

Open Xcode → Settings → Accounts. Click +, pick Apple ID, and sign in with the account that owns your developer membership. The team you want to ship under should appear under your Apple ID row; click it and confirm the Team ID matches the one you'll paste into LingCode.

4. A distribution certificate in your login keychain

xcodebuild signs the archive with a "Apple Distribution" (or legacy "Mac App Distribution") certificate. The easiest way to get one is to let Xcode generate it the first time you archive — but you can also create it yourself:

• Xcode Settings → Accounts → Manage Certificates → + → Apple Distribution. Xcode creates the cert and adds it to your login keychain.

Sanity-check in Terminal:

security find-identity -v -p codesigning | grep -i distribution

You should see a line like 1) 1A2B... "Apple Distribution: Your Name (HPTTZS5J27)". The 10-character code in parentheses is your Team ID — it must match the Team ID field in LingCode.

5. An app record in App Store Connect

Apple will not accept uploads for a bundle identifier that doesn't exist yet. Create the record first:

1. Sign in at appstoreconnect.apple.com.
2. My Apps → + → New App.
3. Platforms: tick iOS, macOS, or both — whichever matches the Xcode target you're shipping. Magic Deploy auto-detects from the scheme and picks the right altool --type.
4. Bundle ID: pick the identifier that matches your Xcode project's Bundle Identifier exactly (shown in the target's General tab). If it's not in the dropdown, register it first at developer.apple.com/account/resources/identifiers as a Mac App identifier (not iOS).
5. SKU: any internal string you'll never reuse. Can't be changed after creation. com-example-myapp is a safe default.
6. User access: leave as Full Access unless you have a reason to restrict.

The record can be completely unfilled — no screenshots, no description, no pricing — and you still can't submit for review, but you can upload builds to it. That's what Magic Deploy does.

Your Xcode project must have these settings

The Apple side can be perfect and the upload will still fail if the .xcodeproj isn't configured for Mac App Store distribution. Open the target's Signing & Capabilities tab and verify each of these:

Signing & Capabilities

• Automatically manage signing — turned on. Magic Deploy's generated ExportOptions.plist sets signingStyle to automatic, so manual signing will conflict.
• Team — set to the same team whose Team ID you'll paste into LingCode. If you see a yellow warning triangle here, click it and resolve (usually just "Add Account").
• Bundle Identifier — matches the app record you created in App Store Connect. Typos (com.example.MyApp vs com.example.myapp) cause rejections at upload time.
• App Sandbox — required for Mac App Store only. Click + Capability if it isn't already there. Enable any entitlements your app actually needs (Network → Outgoing Connections, File Access, etc.) — don't enable everything "just in case", each entitlement is reviewed. (iOS targets skip this — iOS apps are sandboxed by default at the OS level.)
• Hardened Runtime — required for Mac App Store only. Xcode adds this automatically for new macOS targets, but older projects may need to add it by hand. (Not applicable to iOS.)

Version and build numbers

In the target's General tab, under Identity:

• Version (CFBundleShortVersionString) — the human-facing version, e.g. 1.2.3. App Store review cares about this.
• Build (CFBundleVersion) — the internal build number. Must be strictly greater than every build you've previously uploaded for the same Version. If you upload 1.2.3 (42), the next upload for 1.2.3 has to be at least 43. Many first-time-with-Magic-Deploy failures are just "I forgot to bump this."

Scheme

LingCode picks the first scheme that xcodebuild -list returns. If your project has multiple schemes (app + tests + a helper target, for example), make sure the one that builds the distributable app comes first — reorder in Xcode → Product → Scheme → Manage Schemes.

Also ensure the scheme is marked Shared in that same dialog. Non-shared schemes live in your personal xcuserdata/ and may not be visible to xcodebuild.

Step 1 — Create an App Store Connect API key

This single step gets you three of the four fields: the Key ID, the Issuer ID, and the .p8 file.

1. Sign in at appstoreconnect.apple.com with the Apple ID that owns your developer account.
2. In the top nav, click Users and Access.
3. Switch to the Integrations tab, then select App Store Connect API in the sidebar (sometimes labelled just Keys).
4. Click the + button to generate a new key. Give it a name like "LingCode Magic Deploy" and pick the access level — App Manager is enough to upload builds; use Admin if you also want LingCode to manage app metadata later.
5. Click Generate. Apple shows a one-time Download API Key link.

After downloading, the file will be named something like AuthKey_ABC123XYZ0.p8. The 10 characters between AuthKey_ and .p8 are your Key ID. The same Key ID appears in the table on the Keys page; the long UUID at the top of that page (above the table, next to Issuer ID) is your Issuer ID.

Copy these into LingCode

• Key ID → paste into the Key ID field.
• Issuer ID → paste into the Issuer ID field.
• .p8 file → click Browse… in LingCode and pick the file you just downloaded.

Step 2 — Get your Team ID

The Team ID lives on a different site — the Apple Developer portal, not App Store Connect.

1. Sign in at developer.apple.com/account with the same Apple ID.
2. In the sidebar, click Membership Details (older accounts may show it as just Membership).
3. Copy the 10-character Team ID.

Step 3 — Click Deploy

With all four fields filled and the .p8 selected, the Deploy to App Store button activates. Before we walk through what LingCode actually runs, here's what the manual version of this would look like — it's worth seeing so the automation makes sense.

The typical archive & upload flow (by hand)

If you were shipping this without Magic Deploy, you'd do roughly this sequence in Xcode and App Store Connect:

1. Create the app record. In App Store Connect → My Apps → +, create a new app with the same bundle ID as your Xcode project. You can't upload a build to an app that doesn't exist yet.
2. Pick the release scheme. In Xcode's scheme dropdown, choose the scheme that builds the distributable target (usually just your app's scheme, in Release configuration — check Product → Scheme → Edit Scheme → Archive).
3. Archive. Product → Archive. Xcode builds the release configuration, code-signs with your team's certificate (automatic signing fetches or creates a Distribution profile on the fly), and produces an .xcarchive bundle in ~/Library/Developer/Xcode/Archives/.
4. Open the Organizer. Xcode jumps to Window → Organizer → Archives automatically when the archive finishes. Pick the archive you just made.
5. Validate (optional but recommended). Click Validate App. Xcode talks to App Store Connect to check the archive — missing icons, wrong Info.plist keys, bad entitlements surface here before you spend time uploading.
6. Distribute App. Click Distribute App → App Store Connect → Upload. Xcode asks about signing (pick Automatically manage signing), then uploads the archive to App Store Connect. On a good connection this takes 1–5 minutes depending on bundle size.
7. Wait for processing. The build lands in App Store Connect in Processing state. Apple's build servers do their own validation, symbolicate crash info, and extract metadata. This takes anywhere from 2 minutes to 30 minutes, outside your control.
8. Submit for review or distribute to TestFlight. Once processing finishes, the build is attachable to a new app version (for App Store review) or to a TestFlight group (for internal/external testers).

The tedious parts are steps 3–6: clicking through Xcode, answering the same signing questions every time, and waiting for the Organizer UI to respond. Magic Deploy replaces all of it.

What LingCode Magic Deploy runs instead

Under the hood, the Deploy to App Store button shells out to the same command-line tools Xcode uses. You can see this in your project's build/ directory while it runs. In order:

1. Find the project and scheme. LingCode looks in the open project folder for a .xcodeproj, then runs xcodebuild -list -project <project> -json to enumerate schemes and picks the first one. There is no scheme override in the UI — if your project has multiple schemes and the first isn't the right one, reorder them in Manage Schemes in Xcode, or for now archive by hand.
2. Archive.

   xcodebuild archive \
     -scheme <scheme> \
     -configuration Release \
     -archivePath build/<scheme>.xcarchive \
     -destination "generic/platform=macOS"

   The destination (generic/platform=macOS or generic/platform=iOS) and the --type flag on altool are chosen automatically from the scheme's SUPPORTED_PLATFORMS. You'll see [App Store] Detected platform: iOS or macOS in the progress log, so you can confirm before it builds.
3. Generate ExportOptions.plist. LingCode writes a three-key plist to build/ExportOptions.plist:

   <key>method</key>        <string>app-store</string>
   <key>teamID</key>        <string><your Team ID></string>
   <key>signingStyle</key>  <string>automatic</string>

   That's why the Team ID field matters — it ends up here, and it must match the team that owns the signing certificate installed in your keychain.
4. Export.

   xcodebuild -exportArchive \
     -archivePath build/<scheme>.xcarchive \
     -exportPath build/AppStoreExport \
     -exportOptionsPlist build/ExportOptions.plist

   This produces build/AppStoreExport/<scheme>.app, a fully signed and packaged app bundle ready for upload.
5. Upload.

   API_PRIVATE_KEYS_DIR=<dir with .p8> xcrun altool \
     --upload-app \
     -f build/AppStoreExport/<scheme>.app \
     --type macos \
     --apiKey <Key ID> \
     --apiIssuer <Issuer ID>

   This is the same altool that Xcode's Distribute App → Upload uses internally. The .p8 you provided is how it signs JWTs to authenticate against App Store Connect.

Every stdout / stderr line from these commands streams into the progress panel in real time, so when something goes wrong (bad certificate, missing entitlement, App Store Connect validation failure) you see the exact error Xcode would have shown you — without having to click through the Organizer to find it.

On success, the build lands in App Store Connect in Processing. After Apple's processing finishes (2–30 minutes, outside LingCode's control), it shows up under TestFlight → Builds and is ready to submit for review or distribute to testers.

Reading the progress log

While Magic Deploy runs, the right-hand panel streams the live output of xcodebuild and xcrun altool. Everything LingCode prefixes with [App Store] is a status marker from LingCode itself; everything else is verbatim output from Apple's tools.

A successful run looks roughly like this, end-to-end:

[App Store] Archiving...
Build settings from command line:
    ...
ArchiveSucceeded
[App Store] Writing ExportOptions.plist...
[App Store] Exporting...
ExportArchive: signing
ExportArchive: writing /…/build/AppStoreExport/MyApp.app
[App Store] Uploading...
*** Upload Progress: ...
No errors uploading '…/MyApp.app'.
[App Store] Upload complete. Check App Store Connect for the new build.

Where to look when things break: scroll to the very end of the log. xcodebuild prints warnings all the way through the build — the real error is almost always in the last 20 lines, usually after the line that begins ** ARCHIVE FAILED **, ** EXPORT FAILED **, or *** Error: .... LingCode's short "Archive failed. Check the log above." message is just a pointer; the diagnostic detail is in the raw output.

Per-phase troubleshooting

Group failures by which phase they happen in — the fix path is different in each.

Archive phase (xcodebuild archive)

This is where most first-time errors surface, because it's the first time your project is actually being built for Release with real signing.

Export phase (xcodebuild -exportArchive)

Upload phase (xcrun altool --upload-app)

What happens after a successful upload

When Magic Deploy finishes, the build is in App Store Connect → your app → TestFlight → macOS → Builds, initially in Processing state. Apple's build servers run their own post-upload validation — symbolicating crash info, scanning for private API usage, extracting metadata. This usually takes 5–30 minutes but can stretch to an hour or more at peak times. You'll get an email when processing finishes (or when it fails with an ITMS- error).

Once processing is done, you have two paths:

• TestFlight — attach the build to an internal or external test group to distribute to testers. Internal testers (up to 100 users with App Store Connect access) get it immediately. External testers require a brief Beta App Review (usually under 24h for minor updates).
• Submit for review — attach the build to a new app version under the macOS App section, fill in the required metadata (description, screenshots, pricing, privacy), and click Add for Review. Review typically takes 24–72 hours for macOS apps.

If the build never shows up at all — not even in Processing — check the email associated with your Apple ID. Apple sends rejection emails (ITMS-90xxx codes) for binaries that failed server-side validation, and those rejected builds don't appear in App Store Connect at all.

Quick reference: where to go when something's wrong

Common mistakes (quick checklist)

• Renaming the .p8 file. LingCode looks for AuthKey_<KeyID>.p8. If you renamed it, either rename it back or make sure the Key ID field matches whatever is between AuthKey_ and .p8 in the filename.
• Wrong access level. A Developer-level key can read but not upload. You need App Manager or Admin.
• Issuer ID vs Key ID confusion. Key ID is 10 characters and shown per-key in the table. Issuer ID is a long UUID (with dashes) shown once at the top of the Keys page.
• Team ID from the wrong team. If your Apple ID is on multiple teams, switch teams in the developer portal first to make sure you copy the right one.
• Bundle ID not registered. The app's bundle identifier needs an App Store Connect record, and the identifier itself needs to exist in Certificates, IDs & Profiles at developer.apple.com. Create the app record in App Store Connect → My Apps → + first, using the same bundle ID as your Xcode project.
• Forgetting to bump Build. Every upload for the same Version needs a higher Build number. This is the single most common cause of second-upload failures — tick Auto-bump build number in the pane to have LingCode run agvtool next-version -all for you.
• Manual signing turned on. Magic Deploy's ExportOptions.plist uses signingStyle = automatic. If your target has manual signing on, the export will fail or produce an unsignable binary.

Security notes

The .p8 private key is the equivalent of a password for your App Store Connect account. Treat it that way: don't commit it to git, don't share it in Slack, and revoke it from the Keys page if a teammate leaves or a laptop is lost. LingCode never uploads the .p8 anywhere — it stays on your Mac and is only handed to Apple's xcrun altool at upload time.

Further reading

Primary sources for the concepts on this page, from Apple and the IETF:

• LingCode deploy glossary — every term on this page, defined.
• App Store Connect API reference (Apple) — what altool and LingCode talk to under the hood.
• Distributing your app for beta testing and releases (Apple) — official Xcode distribution guide.
• Code Signing Guide (Apple) — deep dive on certs, profiles, and what signing actually proves.
• RFC 7519 — JSON Web Token — the JWT spec Apple's API uses for auth.
• TestFlight (Apple) — the beta service your uploads land in first.