Skip to content
Skills Library
DevOps & cloud · Automation

asc-xcode-build

/asc-xcode-build

Build, archive, export, and manage Xcode version/build numbers with asc, including portable iOS compilation and packaging. Use when creating an IPA or PKG for App Store Connect, TestFlight, or registered-device release testing.

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Build, archive, export, and manage Xcode version/build numbers with asc, including portable iOS compilation and packaging. Use when creating an IPA or PKG for App Store Connect, TestFlight, or registered-device release testing.

Original author description

Build, archive, export, and manage Xcode version/build numbers with asc, including portable iOS compilation and packaging. Use when creating an IPA or PKG for App Store Connect, TestFlight, or registered-device release testing.

How it works

  1. Preconditions
  2. Manage version and build numbers
  3. Compile without archiving
  4. Preferred iOS/tvOS/visionOS build flow
  5. macOS App Store flow
  6. Raw xcodebuild fallback
  7. Troubleshooting
  8. Notes
Original SKILL.md headings · 230 lines, 1,038 words
SKILL.md preview
---
name: asc-xcode-build
description: Build, archive, export, and manage Xcode version/build numbers with asc, including portable iOS compilation and packaging. Use when creating an IPA or PKG for App Store Connect, TestFlight, or registered-device release testing.
---

# Xcode build and export

Use this skill when you need to build an app from source and prepare it for App Store Connect. Prefer `asc xcode archive` and `asc xcode export` over raw `xcodebuild` recipes when they fit the project.

## Preconditions

For a prepared xtool package on Linux, use [portable iOS builds](references/portable-ios.md)
instead of the Xcode commands below. That workflow has a narrower project and signing contract.

- Xcode and command line tools are installed.
- Signing identity and provisioning profiles are available, or automatic signing is enabled.
- App Store Connect auth is configured when upload or build lookup is needed.

## Manage version and build numbers

```bash
asc xcode version view
asc xcode version edit --version "1.3.0" --build-number "42"
asc xcode version edit --next-build-number --app "APP_ID" --platform IOS
asc xcode version bump --type build
asc xcode version bump --type patch
asc xcode version bump --type build --next-build-number --app "APP_ID" --platform IOS
```

Use `--project-dir "./MyApp"` when not running from the project root. Use `--project "./MyApp/App.xcodeproj"` when the directory contains multiple projects. Use `--target "App"` and `--configuration "Release"` for deterministic reads and writes in multi-target or multi-configuration projects.

To avoid low build-number rejects, resolve and apply the remote-safe build number in one command:

```bash
asc xcode version edit --next-build-number --app "APP_ID" --platform IOS --output json
```

Version mutations validate the full change before writing and return structured output identifying the configurations and files changed. The editor follows recursive xcconfig includes and preserves unrelated project and xcconfig content. Use `asc builds next-build-number` separately when you only want to inspect the remote-safe value without changing the project.

Version commands read project and xcconfig settings without launching Xcode. When those settings cannot resolve the version values, the default `--xcodebuild-settings-lookup auto` falls back to `xcodebuild -showBuildSettings` and warns on stderr. Use `--xcodebuild-settings-lookup never` in automation that must not launch Xcode implicitly.

## Compile without archiving

Use `asc xcode build` for an ordinary simulator, device, or CI validation build. Provide exactly one project or workspace and a scheme.

```bash
asc xcode build \
  --project "App.xcodeproj" \
  --scheme "App" \
  --destination "platform=iOS Simulator,name=iPhone 17 Pro Max,OS=27.0" \
  --no-code-signing \
  --result-bundle-path ".asc/artifacts/App.xcresult" \
  --output json
```

When `--derived-data-path` is omitted, asc uses a stable cache outside the source checkout. The result-bundle destination must not already exist. Xcode logs go to stderr and the structured result goes to stdout.

## Preferred iOS/tvOS/visionOS build flow

### 1. Archive with asc

```bash
asc xcode archive \
  --workspace "App.xcworkspace" \
  --scheme "App" \
  --configuration Release \
  --clean \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --xcodebuild-flag=-destination \
  --xcodebuild-flag=generic/platform=iOS \
  --output json
```

Use `--project "App.xcodeproj"` instead of `--workspace` for project-only apps.

### 2. Export with asc

By default, `asc xcode export` generates App Store Connect export options with automatic signing. It uses a local export destination unless `--wait` is set, in which case it uses direct upload:

```bash
asc xcode export \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --ipa-path ".asc/artifacts/App.ipa" \
  --xcodebuild-flag=-allowProvisioningUpdates \
  --output json
```

Generate a plist separately when it needs review, reuse, or manual signing:

```bash
asc xcode export-options generate \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --output-path ".asc/ExportOptions.plist" \
  --output json
```

For manual signing, add `--signing-style manual` and optionally `--team-id "TEAM_ID"`. Existing files require `--overwrite`.

For an IPA installable on registered devices, use Xcode's current
`release-testing` method. The older `ad-hoc` spelling is deprecated by Xcode and
is not accepted by `asc`:

```bash
asc xcode export \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --ipa-path ".asc/artifacts/App.ipa" \
  --method release-testing \
  --signing-style manual \
  --team-id "TEAM_ID" \
  --output json
```

Generate the release-testing plist separately when it needs review or reuse:

```bash
asc xcode export-options generate \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --method release-testing \
  --signing-style manual \
  --team-id "TEAM_ID" \
  --output-path ".asc/ExportOptions.release-testing.plist" \
  --output json
```

`release-testing` always exports locally and cannot be combined with `--wait`.
An explicit `--export-options` plist cannot be combined with `--method`,
`--signing-style`, or `--team-id`. For device/profile reconciliation, isolated
signing, private publication, resumability, and live verification, use the
`asc-ad-hoc-distribution` skill instead of assembling those stages manually.

To upload directly through Xcode and wait for App Store Connect processing, omit `--export-options` and add `--wait`:

```bash
asc xcode export \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --ipa-path ".asc/artifacts/App.ipa" \
  --wait \
  --output json
```

### 3. Upload or publish

Upload an exported IPA:

```bash
asc builds upload --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --wait
```

Distribute to TestFlight:

```bash
asc publish testflight --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --group "GROUP_ID" --wait
```

Publish to the App Store:

```bash
asc publish appstore --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --version "1.2.3" --wait
asc publish appstore --app "APP_ID" --ipa ".asc/artifacts/App.ipa" --version "1.2.3" --wait --submit --confirm
```

## macOS App Store flow

Archive with the helper:

```bash
asc xcode archive \
  --project "MacApp.xcodeproj" \
  --scheme "MacApp" \
  --configuration Release \
  --clean \
  --archive-path ".asc/artifacts/MacApp.xcarchive" \
  --xcodebuild-flag=-destination \
  --xcodebuild-flag=generic/platform=macOS \
  --output json
```

If your macOS export produces a `.pkg`, export it with the helper, then upload the package:

```bash
asc xcode export \
  --archive-path ".asc/artifacts/MacApp.xcarchive" \
  --pkg-path ".asc/artifacts/MacApp.pkg" \
  --xcodebuild-flag=-allowProvisioningUpdates \
  --output json

asc builds upload \
  --app "APP_ID" \
  --pkg ".asc/artifacts/MacApp.pkg" \
  --version "1.0.0" \
  --build-number "123" \
  --wait
```

For `.pkg` uploads, `--version` and `--build-number` are required because they are not auto-extracted like IPA metadata. Add `--export-options "ExportOptions.plist"` when the project needs a custom export configuration.

## Raw xcodebuild fallback

Use raw `xcodebuild` only when neither `asc xcode archive --help` nor
`asc xcode export --help` covers a project-specific option. Prefer passing
extra arguments through `--xcodebuild-flag` first.

```bash
xcodebuild -showBuildSettings -scheme "App"
```

## Troubleshooting

### No profiles for bundle ID during export

- Add `--xcodebuild-flag=-allowProvisioningUpdates` to `asc xcode export`.
- Verify the Apple ID is logged into Xcode.
- Verify profiles with the `asc-signing-setup` skill.

### CFBundleVersion too low

```bash
asc xcode version edit --next-build-number --app "APP_ID" --platform IOS
```

Then rebuild and upload again.

### Build rejected for missing macOS icon

macOS requires ICNS icons with all required sizes. Fix the asset catalog, rebuild, then export/upload again.

## Notes

- Prefer `asc xcode archive` and `asc xcode export` for deterministic local artifacts.
- The default generated export method remains `app-store-connect`; request `--method release-testing` explicitly for registered-device installs.
- Use `--overwrite` only when replacing existing local artifacts intentionally.
- Use `--wait` on upload/publish paths when the next step depends on processed builds.
- For submission readiness, use `asc-submission-health`.
Files in this package (2)
  • SKILL.md 8 KB
  • references/portable-ios.md 2 KB

Versions

RepositoryScoreLicence
This page · rorkai/app-store-connect-cli-skills100MIT
JordanCoin/ios-skills-collection95MIT

Identical content appears in 3 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 27aec1f06830 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100asc-release-flow
    End-to-end release workflows for TestFlight and App Store using asc publish, builds, versions, and submit commands. Use when uploading a build to App Store Connect, distributing to TestFlight beta testers, submitting to App Store review, managing iOS/macOS/visionOS/tvOS…
  • 100ios-release
    Build, archive, and prepare iOS app for TestFlight/App Store. Handles version bumping, build number configuration, Xcode archiving, and upload. Use when preparing a new iOS release for TestFlight beta testing or App Store submission.
  • 100asc-cli
    Use the asc (App Store Connect CLI) to manage iOS/macOS apps — TestFlight builds, beta groups, distribution, App Store submissions, release, user reviews, analytics reports, crash logs, and more. Triggers when user mentions "asc", "TestFlight", "beta test", "app store review",…
  • 100asc-api-automation
    Use when automating App Store Connect from a script or CI via the ASC REST API (`api.appstoreconnect.apple.com`) — ASC API `.p8` key / JWT auth, TestFlight `betaGroups` / `betaBuildLocalizations`, `appStoreVersions` / `releaseType`, `reviewSubmissions`, `salesReports`,…
  • 100asc-hub
    Ship an iOS app through App Store Connect with the asc_hub tool. Use when the session built a build and the user wants to install the asc engine, check or set up App Store Connect sign-in, list apps and builds, upload to TestFlight, distribute to testers, submit for App Review,…
  • 100rork-local
    Preview an iOS app in a live simulator tab and publish it to TestFlight or the App Store with rork-local. Use when the user wants to run rork-local, see their app in the browser-based simulator, capture or frame App Store screenshots, or publish a built .ipa via the asc CLI from localhost.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.