asc-ad-hoc-distribution

ASC アドホック配布

実験的な asc distribute ワークフローを使用すると、既存の iOS アーカイブを、登録済みデバイス向けの非公開の検証済みインストールリンクに変換できます。Apple がホストする配布を利用する場合は、代わりに TestFlight または App Store リリースのスキルを使用してください。

実行前に、インストール済みのコントラクトを確認してください。

asc distribute --help
asc distribute plan --help
asc distribute apply --help
asc distribute resume --help
asc distribute status --help
asc distribute verify --help

ワークフローを選択する

• .xcarchive から開始する、ハッシュ認証済みのエンドツーエンド実行には、plan -> apply -> resume/status -> verify を使用してください。
• 呼び出し元がすでにアドホック IPA を所有しており、より低レベルの境界を個別に操作したい場合に限り、inspect -> prepare -> publish を使用してください。

ガードレール

• 配布仕様、デバイスファイル、PKCS#12 ID、パスワードファイル、実行状態、正確なインストールリンクの成果物は非公開として扱ってください。Git に含めず、所有者のみがアクセスできる権限を必須としてください。
• S3 の認証情報や署名付き URL を、配布仕様、コマンド出力、ログ、課題、チャットに記載しないでください。ASC_S3_ACCESS_KEY_ID、ASC_S3_SECRET_ACCESS_KEY、および任意の ASC_S3_SESSION_TOKEN、または標準の AWS SDK 認証情報チェーンを使用してください。
• plan は読み取り専用であり、ready: false でも正常終了する場合があります。続行する前に、型付きブロッカーと影響を確認してください。
• apply は、不足しているデバイスの登録、安全な App ID と後継のアドホックプロファイルの作成、ローカル成果物の書き込み、不変オブジェクトの公開を行う場合があります。ユーザーが正確なプランハッシュと影響一覧を承認した後にのみ実行してください。
• オーケストレーションされたワークフローは、既存の S3 互換バケットへの非公開アクセスをサポートします。バケットの作成、ポリシーの変更、古いビルドの削除、アプリのインストールや起動は行いません。
• 入力のドリフト、不変オブジェクトの競合、署名素材の期限切れ、非公開リンクの期限切れが発生した場合は、新しいプランが必要です。古い実行を無理に続行しないでください。

前提条件

• メインアプリのターゲットが 1 つの既存の iOS .xcarchive。埋め込みアプリ、拡張機能、Watch アプリ、App Clip がある場合、v1 プランは準備未完了になります。
• ローカルの iOS 配布用 PKCS#12 ID と、任意の保護されたパスワードファイル。
• 保護された strict-v1 デバイスファイル。例：

{"schemaVersion":1,"devices":[{"name":"Test iPhone","udid":"DEVICE_UDID","platform":"IOS"}]}

• デバイス、Bundle ID、証明書、プロファイルにアクセスできる App Store Connect 認証情報。
• 既存の S3 互換バケットと有効な認証情報。

1. 非公開の配布仕様を作成する

相対パスは仕様ファイルのディレクトリを基準に解決されます。仕様では環境変数を展開せず、認証情報も受け付けません。非公開設定の例：

{
  "schemaVersion": 1,
  "devicesFile": "devices.json",
  "signing": {
    "identity": {
      "format": "pkcs12",
      "path": "../signing/distribution.p12",
      "passwordFile": "../secrets/distribution-p12-password"
    },
    "minimumValidityDays": 7,
    "maxMutations": 32
  },
  "publication": {
    "endpoint": "https://objects.example.com",
    "downloadEndpoint": "https://downloads.example.com",
    "region": "auto",
    "bucket": "ios-builds",
    "prefix": "team/app",
    "addressingStyle": "path",
    "urlTtl": "24h",
    "downloadGrace": "1h",
    "verifyTimeout": "30s"
  },
  "metadata": {
    "title": "App",
    "channel": "pull-request-42",
    "sourceRevision": "abc123",
    "sourceUrl": "https://example.com/team/app/commit/abc123"
  }
}

passwordFile、certificateSha256、downloadEndpoint、およびすべてのメタデータフィールドは任意です。パスワードファイルを省略した場合、PKCS#12 のパスワードは空である必要があります。プラン作成前に、設定ファイルとシークレット入力を保護してください。

chmod 600 ".asc/distribution/config.json" ".asc/distribution/devices.json"
chmod 600 ".asc/signing/distribution.p12" ".asc/secrets/distribution-p12-password"

2. 変更を加えずにプランを作成する

asc distribute plan \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --config ".asc/distribution/config.json" \
  --plan ".asc/distribution/plan.json" \
  --state-dir ".asc/distribution/runs" \
  --output json

ready、planHash、署名の有効性、保存先、順序付けされた effects の完全な一覧を確認してください。ブロッカーを解決し、ready が false の場合は新しいプランを作成してください。終了コードだけから準備状況を判断しないでください。

3. 承認された正確なプランを適用する

影響が正確に承認された後、64 文字の完全なハッシュを渡してください。

PLAN_HASH="$(jq -er '.planHash' ".asc/distribution/plan.json")"
asc distribute apply \
  --plan ".asc/distribution/plan.json" \
  --confirm "$PLAN_HASH" \
  --output json

確認がない場合、形式が正しくない場合、または一致しない場合は、副作用が発生する前に拒否されます。成功は、公開とライブ取得の検証が完了したことを意味します。デバイスへのアプリのインストールや起動を意味するものではありません。

4. 検査、再開、検証

返された runId を使用します。

asc distribute status --run "RUN_ID" --state-dir ".asc/distribution/runs" --output json
asc distribute resume --run "RUN_ID" --state-dir ".asc/distribution/runs" --output json
asc distribute verify --run "RUN_ID" --state-dir ".asc/distribution/runs" --timeout 30s --output json

status はローカルでのみ動作し、running、recoverable、blocked の各実行で成功します。文章ではなく、型付きフィールドに基づいて分岐してください。resume は再試行前に永続化された証拠を再検証し、リモートへの書き込みを決して無条件に繰り返しません。verify は読み取り専用ですが、ライブ取得を実行します。接続されたデバイス上で、該当するインストール済みバンドル、バージョン、ビルドを確認するようユーザーから依頼された場合に限り、--device "DEVICE_SELECTOR" を追加してください。この確認によって IPA のバイト単位の同一性が証明されるわけではありません。

正確なプライベートインストール URL はベアラー資格情報であり、完了した実行が報告する所有者専用リンクアーティファクトにのみ保存されます。承認済みのプライベートなチャネルを通じて、対象のテスターにのみ共有してください。

低レベル IPA ワークフロー

署名とエクスポートがすでに完了している場合は、このレーンを使用します。prepare が返す正確な bundleDir を publish に渡します。

asc distribute inspect --ipa ".asc/artifacts/App.ipa" --output json
asc distribute prepare --ipa ".asc/artifacts/App.ipa" --channel "pull-request-42" --output json
asc distribute publish \
  --bundle-dir ".asc/distribution/com.example.app/1.2-42-IPA_SHA_PREFIX" \
  --endpoint "https://objects.example.com" \
  --region "auto" \
  --bucket "ios-builds" \
  --prefix "team/app" \
  --receipt ".asc/publishes/app-1.2-42.json" \
  --link-path ".asc/publishes/app-1.2-42-link.json" \
  --output json

inspect は、--include-devices が明示的に必要な場合を除き、生のデバイス UDID を省略します。prepare はバンドルを上書きせず、完全に同等なものだけを再利用します。プライベートな publish がデフォルトであり、正確な署名付きリンクはモード 0600 のリンクアーティファクトにのみ書き込みます。公開での配布は、--access public --public-base-url を使用する別個の明示的なレーンです。匿名読み取りがすでに設定されていることを前提とし、ストレージポリシーは変更しません。