asc-xcode-build

Xcode でのビルドとエクスポート

ソースからアプリをビルドし、App Store Connect 向けに準備する必要がある場合に、このスキルを使用してください。プロジェクトに適している場合は、生の xcodebuild レシピよりも asc xcode archive と asc xcode export を優先してください。

前提条件

Linux で準備済みの xtool パッケージを使用する場合は、以下の Xcode コマンドではなく、ポータブル iOS ビルド を使用してください。このワークフローでは、対象となるプロジェクトと署名の要件がより限定されています。

• Xcode とコマンドラインツールがインストールされていること。
• 署名 ID とプロビジョニングプロファイルが利用可能であること、または自動署名が有効になっていること。
• アップロードまたはビルドの検索が必要な場合、App Store Connect の認証が設定されていること。

バージョン番号とビルド番号を管理する

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

プロジェクトのルート以外から実行する場合は --project-dir "./MyApp" を使用してください。ディレクトリに複数のプロジェクトが含まれている場合は --project "./MyApp/App.xcodeproj" を使用してください。複数のターゲットまたは構成があるプロジェクトで値を確実に読み書きするには、--target "App" と --configuration "Release" を使用してください。

低いビルド番号による却下を避けるため、リモートで安全なビルド番号の取得と適用を 1 つのコマンドで行います。

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

バージョンの変更では、書き込み前に変更全体を検証し、変更された構成とファイルを示す構造化された出力を返します。エディターは xcconfig の再帰的なインクルードをたどり、無関係なプロジェクトおよび xcconfig の内容を保持します。プロジェクトを変更せずにリモートで安全な値だけを確認する場合は、asc builds next-build-number を別途使用してください。

バージョンコマンドは、Xcode を起動せずにプロジェクトと xcconfig の設定を読み取ります。これらの設定からバージョン値を解決できない場合、既定の --xcodebuild-settings-lookup auto は xcodebuild -showBuildSettings にフォールバックし、標準エラーに警告を出します。Xcode を暗黙的に起動してはならない自動化では、--xcodebuild-settings-lookup never を使用してください。

アーカイブせずにコンパイルする

通常のシミュレーター、デバイス、または CI の検証ビルドには asc xcode build を使用してください。プロジェクトまたはワークスペースを 1 つだけ指定し、スキームも指定してください。

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

--derived-data-path を省略すると、asc はソースチェックアウトの外部にある安定したキャッシュを使用します。結果バンドルの保存先は、すでに存在していてはなりません。Xcode のログは標準エラーに、構造化された結果は標準出力に出力されます。

推奨する iOS／tvOS／visionOS ビルドフロー

1. asc でアーカイブする

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

プロジェクトのみのアプリでは、--workspace の代わりに --project "App.xcodeproj" を使用してください。

2. asc でエクスポートする

既定では、asc xcode export は自動署名を使用する App Store Connect 用のエクスポートオプションを生成します。--wait を指定しない場合はローカルのエクスポート先を使用し、指定した場合は直接アップロードします。

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

確認、再利用、または手動署名が必要な場合は、plist を別途生成してください。

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

手動署名の場合は --signing-style manual を追加し、必要に応じて --team-id "TEAM_ID" を指定してください。既存のファイルがある場合は --overwrite が必要です。

登録済みデバイスにインストール可能な IPA を作成するには、Xcode の現在の release-testing メソッドを使用してください。以前の表記である ad-hoc は Xcode では非推奨であり、 asc では受け付けられません。

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

確認または再利用が必要な場合は、release-testing 用の plist を別途生成してください。

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 は常にローカルにエクスポートするため、--wait と併用できません。 明示的な --export-options plist は、--method、--signing-style、 または --team-id と併用できません。デバイス／プロファイルの照合、分離された 署名、プライベート配布、再開可能な処理、ライブ検証を行う場合は、これらの段階を手動で組み立てるのではなく、 asc-ad-hoc-distribution スキルを使用してください。

Xcode を通じて直接アップロードし、App Store Connect の処理完了を待つには、--export-options を省略して --wait を追加します。

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

3. アップロードまたは公開する

エクスポート済みの IPA をアップロードします。

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

TestFlight に配布します。

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

App Store で公開します。

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 のフロー

ヘルパーを使ってアーカイブします。

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

macOS のエクスポートで .pkg が生成される場合は、ヘルパーを使ってエクスポートしてから、パッケージをアップロードします。

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

.pkg のアップロードでは、IPA のメタデータのように自動抽出されないため、--version と --build-number が必須です。プロジェクトでカスタムのエクスポート設定が必要な場合は、--export-options "ExportOptions.plist" を追加します。

raw xcodebuild へのフォールバック

プロジェクト固有のオプションが asc xcode archive --help にも asc xcode export --help にも記載されていない場合に限り、raw xcodebuild を使います。 まずは --xcodebuild-flag で追加の引数を渡してください。

xcodebuild -showBuildSettings -scheme "App"

トラブルシューティング

エクスポート時にバンドル ID に対応するプロファイルがない

• asc xcode export に --xcodebuild-flag=-allowProvisioningUpdates を追加します。
• Apple ID で Xcode にログインしていることを確認します。
• asc-signing-setup スキルでプロファイルを確認します。

CFBundleVersion が低すぎる

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

その後、再ビルドして再度アップロードします。

macOS アイコンがないためビルドが拒否される

macOS では、必要なすべてのサイズを含む ICNS アイコンが必要です。アセットカタログを修正し、再ビルドしてから、再度エクスポート／アップロードします。

注記

• 決定性の高いローカルアーティファクトを作成するには、asc xcode archive と asc xcode export を優先します。
• 生成されるエクスポート方法のデフォルトは引き続き app-store-connect です。登録済みデバイスへのインストールでは、--method release-testing を明示的に指定します。
• 既存のローカルアーティファクトを意図的に置き換える場合に限り、--overwrite を使います。
• 次の手順で処理済みビルドが必要な場合は、アップロード／公開の処理で --wait を使います。
• 提出準備状況の確認には、asc-submission-health を使います。