Skills

xcode-archive-release

Installation
SKILL.md

Xcode Archive & Release

Release an Apple app by bumping version/build metadata, archiving with Xcode, exporting and uploading to App Store Connect, then tagging the released HEAD in git.

Use when

  • The user wants to archive and upload an iOS or macOS app to App Store Connect
  • The user wants to release from an explicit version/build or infer them from a git tag
  • The user needs to retry an upload without rebuilding unless necessary

Prerequisites

  • macOS with Xcode and xcodebuild available
  • A signed Xcode project with a valid scheme
  • Access to the correct Apple Developer team and App Store Connect account
  • A clean understanding of the target project, scheme, platform list, version, and build number

The main helper is scripts/xcode-release.sh. The bundled assets/ExportOptions-AppStore.plist sets method=app-store and destination=upload, so the default flow uploads directly to App Store Connect without a separate altool step. After a successful automatic upload, the script creates the annotated git tag v<version>-<build> on the current HEAD and pushes that exact tag to the branch's upstream remote, or origin if no upstream remote is configured.

Confirm before acting

Before running the script, confirm:

  • the Xcode project path
  • the scheme name
  • the version and build number, or that git tag inference is intended
  • the target platform list: any ordered subset of ios, macos, and mac_catalyst
  • whether the user wants a preflight-only validation run first

For mixed-target or higher-risk projects, prefer a dry run with --preflight-only before touching source files.

Workflow

1. Discover project details

If the user hasn't specified --project or --scheme, find them:

# List .xcodeproj files near the current directory
find . -name "*.xcodeproj" -maxdepth 3

# List available schemes for a project
xcodebuild -project MyApp.xcodeproj -list

2. Confirm before running

Present a dry-run summary to the user before executing:

Project : MyApp.xcodeproj
Scheme  : MyApp_iOS
Version : 2.1.0  Build: 42
Platform: ios (generic/platform=iOS)
Archive : ~/.xcode-archive/MyApp/2.1.0-42/MyApp-ios.xcarchive

For complex or mixed-target projects (e.g. iOS + watchOS), run --preflight-only first to validate the scheme and export plist before any source files are touched:

xcode-release.sh --project MyApp.xcodeproj --scheme MyApp_iOS --version 2.1.0 --build 42 --preflight-only

Ask for confirmation, then proceed.

3. Run the script

Run the bundled script:

chmod +x path/to/skills/xcode-archive-release/scripts/xcode-release.sh

# Infer version + build from the git tag on HEAD (tag must contain both components):
path/to/skills/xcode-archive-release/scripts/xcode-release.sh \
  --project  MyApp/MyApp.xcodeproj \
  --scheme   MyApp_iOS \
  --platform ios,macos

# Or specify explicitly:
path/to/skills/xcode-archive-release/scripts/xcode-release.sh \
  --project  MyApp/MyApp.xcodeproj \
  --scheme   MyApp_iOS \
  --version  2.1.0 \
  --build    42 \
  [--platform ios|macos|mac_catalyst[,ios|macos|mac_catalyst...]] \
  [--export-plist /custom/ExportOptions.plist]  \  # override bundled plist
  [--preflight-only]           # validate setup without building or touching source
  [--force]                    # re-archive even if archive already exists

When multiple platforms are listed, the script builds them sequentially in the order provided. Version/build resolution happens once for the whole batch.

Git tag format — must contain exactly one semver component and one integer component, separated by -, +, /, or _. Leading v is stripped.

Tag Version Build
v2.1.0-42 2.1.0 42
2.1.0+42 2.1.0 42
2.1.0/42 2.1.0 42
v2.1.0 ✗ no build —
release-2.1.0-42 ✗ ambiguous —

If the tag is ambiguous or missing a component, the script errors with a message directing you to pass --version and --build explicitly.

4. Create and push release tag

After a successful automatic upload, the script creates and pushes an annotated release tag:

  • tag format: v<version>-<build>
  • example: v2.1.0-42
  • tag message: Release 2.1.0 (42)

The tag is created on the current HEAD. The script does not create a git commit for the version/build edits it made during the release. If those edits are still uncommitted, the tag still points at the pre-existing HEAD commit.

If the tag already exists locally or on the remote, the script fails without moving or force-pushing the tag.

5. Report results

On success, the script prints the artifact path. Tell the user:

  • Where artifacts are: ~/.xcode-archive/<project-name>/<version>-<build>/
  • To check App Store Connect → TestFlight or the Builds tab to confirm the upload processed
  • Which git tag was created and which remote it was pushed to

The platform variant is ios, macos, or mac_catalyst. The script keeps the same version/build folder and makes the archive, export, DerivedData, and log names platform-specific.

If the archive succeeds but automatic export/upload hits a missing App Store provisioning profile for the app’s bundle ID, the script opens the .xcarchive in Xcode Organizer instead. In that case, tell the user the archive is ready and they should upload it to App Store Connect manually from Organizer.

Output

Successful runs produce:

  • a versioned archive folder at ~/.xcode-archive/<ProjectName>/<version>-<build>/
  • the .xcarchive
  • exported artifacts under export-<platform-variant>/
  • logs under logs-<platform-variant>/archive.log and logs-<platform-variant>/export.log
  • a per-platform completion marker used to skip already completed variants on rerun
  • an annotated git tag v<version>-<build> pushed to the configured remote after automatic upload succeeds

The user should verify the build appears in App Store Connect after processing finishes.

Retry a Failed Upload

If one platform in a batch fails (network issue, ASC outage, etc.):

  1. If the original run already pinned version/build explicitly, or inferred them from a git tag, run the exact same command — already completed platforms are skipped, and incomplete platforms are retried in sequence.
  2. If the original run inferred version/build from archive history, use the retry command printed on failure instead. That retry command pins the resolved --version and --build, so it retries the same release instead of advancing to the next build number.
  3. Use --force only if you need to rebuild all listed platforms from scratch (e.g. wrong code was archived).

If upload succeeded but tag creation or tag push failed, do not re-run the full release command blindly. The binary may already be uploaded, and a retry can fail with duplicate upload or duplicate tag errors. Use the script's tag-specific failure message to decide whether to create or push the tag manually.

Output Folder Structure

~/.xcode-archive/<ProjectName>/
└── <version>-<build>/              e.g. 2.1.0-42/
    ├── MyApp-ios.xcarchive         iOS archive
    ├── MyApp-macos.xcarchive       macOS archive when present
    ├── MyApp-mac_catalyst.xcarchive Catalyst archive when present
    ├── DerivedData-ios/            isolated DerivedData per platform variant
    ├── DerivedData-macos/
    ├── DerivedData-mac_catalyst/
    ├── export-ios/                 export output
    │   ├── MyApp.ipa
    │   ├── ExportOptions.plist     copy of the options used
    │   └── UploadSessionLogs/      ASC upload diagnostic logs
    ├── export-macos/
    ├── export-mac_catalyst/
    ├── logs-ios/
    │   ├── archive.log             full xcodebuild archive output
    │   └── export.log              full xcodebuild -exportArchive output
    ├── logs-macos/
    ├── logs-mac_catalyst/
    ├── .completed-ios
    ├── .completed-macos
    └── .completed-mac_catalyst

Each run has its own versioned folder, and each platform variant gets its own artifact names inside that folder. That lets the same version/build coexist across platforms without overwriting the archive.

Bundled files

  • scripts/xcode-release.sh — main release workflow
  • assets/ExportOptions-AppStore.plist — default App Store export settings

Troubleshooting

Symptom Fix
Code signing failed Open Xcode → project target → Signing & Capabilities, ensure a valid provisioning profile and team are set for Release
error: exportArchive No profiles for '<bundle-id>' were found Treat this as an Organizer handoff: open the generated .xcarchive in Xcode Organizer and tell the user to upload it to App Store Connect manually
No schemes found Run xcodebuild -project MyApp.xcodeproj -list to list valid scheme names; or use --preflight-only to check before running
ERROR ITMS-90189: Duplicate binary upload The build number already exists in ASC. Increment --build
Duplicate platform in --platform list Remove repeated platform entries. Each batch should list each of ios, macos, and mac_catalyst at most once
Archive not found on retry Check the path ~/.xcode-archive/<name>/<version>-<build>/<name>-<platform-variant>.xcarchive exists; if not, re-run with the same --platform list used for the original archive
PlistBuddy: Entry, ":CFBundleShortVersionString", Does Not Exist Harmless — the Info.plist doesn't have that key (modern Xcode projects); the project.pbxproj patch handles it
No git tag on HEAD HEAD isn't tagged. Create a tag (git tag v2.1.0-42 && git push --tags) or pass --version and --build explicitly
Tag(s) on HEAD ... don't contain one semver + one integer component Tag is missing the build number (e.g. v2.1.0) or has an unrecognised part (e.g. release-2.1.0-42). Rename the tag or pass --version/--build explicitly
Script fails with ✗ FAILED at step: archive Check ~/.xcode-archive/<name>/<ver>-<build>/logs-<platform-variant>/archive.log for the root cause; the failure block prints the last 20 lines automatically
Release tag already exists locally The current repo already has v<version>-<build>. Do not force-move it; use a new build number if this is a new release attempt
Release tag already exists on remote The remote already has v<version>-<build>. Treat the tag as immutable; verify whether the release already happened before retrying
✗ FAILED at step: tag after upload succeeded The app upload completed but tagging did not. Follow the printed recovery command to push the local tag, or resolve the duplicate-tag/git-remote issue manually

ExportOptions Customization

The bundled plist (assets/ExportOptions-AppStore.plist) works for standard App Store uploads. To customize (e.g. add teamID, signingStyle, or iCloudContainerEnvironment), copy it to the project folder and pass --export-plist:

cp path/to/skills/xcode-archive-release/assets/ExportOptions-AppStore.plist ./ExportOptions.plist
# edit as needed
xcode-release.sh ... --export-plist ./ExportOptions.plist
Installs
12
Repository
grepug/skills
First Seen
Mar 15, 2026