asc-signing-setup

asc signing setup

當需要為 iOS/macOS 應用程式建立或更新簽署資產時，請使用此 Skill。

前置條件

• 已完成驗證設定（透過 asc auth login 或 ASC_* 環境變數）。
• 已確認 Bundle Identifier 與目標平台。
• 已準備好用於建立憑證的 CSR 檔案，或預計由 asc certificates create --generate-csr 自動生成。

工作流程

1. 建立或查詢 Bundle ID：
   • asc bundle-ids list --paginate
   • asc bundle-ids create --identifier "com.example.app" --name "Example" --platform IOS
2. 設定 Bundle ID 的功能權限（Capabilities）：
   • asc bundle-ids capabilities list --bundle "BUNDLE_ID"
   • asc bundle-ids capabilities add --bundle "BUNDLE_ID" --capability ICLOUD
   • 必要時新增功能詳細設定：
     • --settings '[{"key":"ICLOUD_VERSION","options":[{"key":"XCODE_13","enabled":true}]}]'
3. 建立簽署憑證：
   • asc certificates list --certificate-type IOS_DISTRIBUTION
   • asc certificates create --certificate-type IOS_DISTRIBUTION --csr "./cert.csr"
   • 或直接在指令中同步生成私鑰與 CSR：
     • asc certificates create --certificate-type IOS_DISTRIBUTION --generate-csr --key-out "./signing/dist.key" --csr-out "./signing/dist.csr"
4. 建立預備描述檔（Provisioning Profile）：
   • asc profiles create --name "AppStore Profile" --profile-type IOS_APP_STORE --bundle "BUNDLE_ID" --certificate "CERT_ID"
   • 開發或 Ad-hoc 用途需包含測試裝置：
     • asc profiles create --name "Dev Profile" --profile-type IOS_APP_DEVELOPMENT --bundle "BUNDLE_ID" --certificate "CERT_ID" --device "DEVICE_ID"
5. 下載描述檔：
   • asc profiles download --id "PROFILE_ID" --output "./profiles/AppStore.mobileprovision"
6. 視需求檢視並於本機安裝已下載的描述檔：
   • asc profiles inspect --path "./profiles/AppStore.mobileprovision" --output table
   • asc profiles inspect --path "./profiles/AppStore.mobileprovision" --entitlements --output markdown
   • asc profiles local install --path "./profiles/AppStore.mobileprovision"
   • asc profiles local list --output table

輪替與清理

• 撤銷舊憑證：
  • asc certificates revoke --id "CERT_ID" --confirm
• 刪除或輪替前，先稽核遠端的預備描述檔：
  • asc profiles list --profile-state ACTIVE,INVALID --paginate --output json
  • Apple 的 profileState 並非完全可靠的過期指標：某些描述檔即使回傳 ACTIVE，其 expirationDate 可能已經過期。若要精確稽核過期的描述檔，請直接比較 expirationDate 與當前日期，而非僅依賴 INVALID 狀態。
• 刪除舊描述檔：
  • asc profiles delete --id "PROFILE_ID" --confirm
• 清理本機 Xcode 的預備描述檔：
  • asc profiles local clean --expired --dry-run
  • asc profiles local clean --expired --confirm

使用 asc signing sync 進行團隊共享儲存

當你需要一種輕量且非互動式的方式，替代 fastlane match 來將憑證與描述檔加密備份至 Git 時，可使用此功能。

# 將當前 ASC 簽署資產推送到加密的 Git 儲存庫
asc signing sync push \
  --bundle-id "com.example.app" \
  --profile-type IOS_APP_STORE \
  --repo "git@github.com:team/certs.git" \
  --password "$MATCH_PASSWORD"

# 拉取並解密至本機目錄
asc signing sync pull \
  --repo "git@github.com:team/certs.git" \
  --password "$MATCH_PASSWORD" \
  --output-dir "./signing"

注意事項：

• --password 未指定時會自動回退使用 ASC_MATCH_PASSWORD。
• 加密儲存庫採用類似 match 風格的 Git 目錄結構來存放憑證與描述檔。
• pull 僅將檔案寫入磁碟；匯入 Keychain 或安裝描述檔為獨立步驟。

注意事項

• 請務必使用 --help 確認確切的列舉值（例如憑證類型、描述檔類型）。
• 帳號內資源較多時，請使用 --paginate 分頁查詢。
• 若需要多張憑證，--certificate 參數可接收以逗號分隔的 ID。
• 裝置管理請使用 asc devices 相關指令（需提供 UDID）。
• asc profiles inspect 與 asc profiles local ... 僅操作本機磁碟狀態，不會呼叫 App Store Connect API 資源。