asc-signing-setup

asc 签名设置

在需要为 iOS/macOS 应用创建或续期签名资产时，请使用此技能。

前提条件

• 已配置身份验证（asc auth login 或 ASC_* 环境变量）。
• 已知应用的 bundle 标识符和目标平台。
• 已准备好用于创建证书的 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 功能：
   • 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_6","enabled":true}]}]'
   • 对于仅限 Developer Portal 的 PRIVATE_CLOUD_COMPUTE 功能，请使用用户所有的 Web 会话和 Developer Portal Bundle ID 资源 ID：
     • asc web bundle-ids capabilities enable --bundle-id "BUNDLE_RESOURCE_ID" --capability PRIVATE_CLOUD_COMPUTE --confirm
     • 此功能不在公开的 App Store Connect 功能枚举中。如果缓存的会话无法访问 Developer Portal，请清除其指定范围的缓存，然后使用同一二进制文件重新登录：
       • asc web auth logout --apple-id "[email protected]"
       • asc web auth login --apple-id "[email protected]"
   • 对于 App Groups，公开 API 可以启用 APP_GROUPS，但无法创建或关联 App Group 资源。请使用 Account Holder 或 Admin Web 会话：
     • asc web app-groups list --paginate --output table
     • asc web app-groups create --name "Example Shared" --identifier "group.com.example.app.shared" --confirm
     • asc web app-groups assign --group "GROUP_RESOURCE_ID" --bundle-id "BUNDLE_RESOURCE_ID" --confirm
     • 使用 asc web app-groups list 查找不透明的组 ID，并使用 asc bundle-ids list 查找不透明的 Bundle ID 资源 ID。更改关联会使包含该 App ID 的配置描述文件失效，因此请在下次签名构建前重新生成受影响的配置描述文件。
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"
   • 对于 Wallet 卡券，请先创建 Pass Type ID，再创建其证书：
     • asc pass-type-ids create --identifier "pass.com.example" --name "Example Pass"
     • asc certificates create --certificate-type PASS_TYPE_ID --pass-type-id "PASS_TYPE_ID" --csr "./pass.csr"
     • asc pass-type-ids certificates list --pass-type-id "PASS_TYPE_ID" --paginate
4. 创建配置描述文件：
   • asc profiles create --name "AppStore Profile" --profile-type IOS_APP_STORE --bundle "BUNDLE_ID" --certificate "CERT_ID"
   • 开发或临时分发时，请包含设备：
     • 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
   • 在 macOS 上，默认目录取决于当前使用的 Xcode：Xcode 16 或更高版本使用 ~/Library/Developer/Xcode/UserData/Provisioning Profiles；Xcode 15 或更低版本使用 ~/Library/MobileDevice/Provisioning Profiles。未安装完整当前 Xcode 的主机将回退到旧版目录，并向 stderr 输出提示。
   • 自动化需要指定固定目录时，请传入 --install-dir。

轮换与清理

• 撤销旧证书：
  • asc certificates revoke --id "CERT_ID" --confirm
• 删除或轮换远程配置描述文件前，先进行审计：
  • asc profiles list --profile-state ACTIVE,INVALID --paginate --output json
  • Apple 的 profileState 不是完整的过期信号：有些配置描述文件的 expirationDate 已是过去的日期，但仍会报告为 ACTIVE。要真正审计过期配置描述文件，请将 expirationDate 与当前日期进行比较，而不要只依赖 INVALID。
• 删除旧配置描述文件：
  • asc profiles delete --id "PROFILE_ID" --confirm
• 清理本地 Xcode 配置描述文件：
  • asc profiles local clean --expired --dry-run
  • asc profiles local clean --expired --confirm
  • 确认前请检查 dry-run 输出中解析出的目录，或使用 --install-dir 固定该目录。

使用 asc signing sync 共享团队存储

当你需要一种轻量、非交互式的 fastlane match 替代方案，用于存储由 git 支持的加密证书和配置描述文件时，请使用此功能。

# Protect secret inputs before use
chmod 600 "./signing-sync-password" "./distribution.p12" "./distribution-p12-password"

# Push a usable private identity with its matching certificate and profile
asc signing sync push \
  --bundle-id "com.example.app" \
  --profile-type IOS_APP_ADHOC \
  --repo "[email protected]:team/certs.git" \
  --password-file "./signing-sync-password" \
  --identity "./distribution.p12" \
  --identity-password-file "./distribution-p12-password" \
  --output json

# Pull and decrypt them into a local directory
asc signing sync pull \
  --repo "[email protected]:team/certs.git" \
  --password-file "./signing-sync-password" \
  --output-dir "./signing" \
  --output json

注意：

• App Store Connect 不会返回私钥。请使用 --identity 提供本地 PKCS#12，或使用 --private-key 和 --identity-sha256 来选择与之匹配的 App Store Connect 证书。包含多个身份的 PKCS#12 也需要 --identity-sha256。
• 优先使用 --password-file；ASC_SIGNING_SYNC_PASSWORD 是非文件形式的备用选项。--password 已在 5.0.0 中移除，使用时会被拒绝。ASC_MATCH_PASSWORD 不再读取；即使已设置，也会被忽略。
• 仅同步证书/配置描述文件仍受支持，但会报告 identityPresent: false；单独使用它并不能构成可用的签名身份。
• pull 会在 sensitiveFiles 中报告私有身份，并以 0600 模式写入。导入或使用拉取的身份仍是单独的显式步骤。
• 私有身份同步不支持 MAC_APP_DIRECT 和 MAC_CATALYST_APP_DIRECT；仅同步证书/配置描述文件仍可用。

协调临时设备和配置描述文件

使用实验性的协调工作流，根据 Xcode 归档和受保护的目标设备文件，执行确定性、增量式更改：

asc signing reconcile plan \
  --archive-path ".asc/artifacts/App.xcarchive" \
  --devices-file ".asc/distribution/devices.json" \
  --output json

asc signing reconcile apply \
  --plan ".asc/distribution/signing/plan.json" \
  --confirm \
  --output json

规划不会执行任何变更，且可能返回 ready: false。应用更改可以注册缺失设备、创建安全的基准 App ID，并创建后续临时配置描述文件；它绝不会删除或修补资源、启用功能或创建证书。请先检查计划，再使用 --confirm。如果这些签名操作需要绑定到端到端的分发计划哈希中，请使用 asc-ad-hoc-distribution skill。

使用临时身份运行单条命令

在 macOS 上，可通过包装子命令来避免对登录钥匙串和配置描述文件进行持久性更改：

asc signing run \
  --identity "./signing/App.p12" \
  --identity-password-file "./signing/App-password" \
  --profile "./signing/App.mobileprovision" \
  --receipt ".asc/distribution/signing-run.json" \
  -- xcodebuild -exportArchive \
    -archivePath ".asc/artifacts/App.xcarchive" \
    -exportPath ".asc/artifacts/release-testing" \
    -exportOptionsPlist ".asc/ExportOptions.release-testing.plist"

该命令会直接运行，不经过 shell；它会保留子命令的退出代码，使用隔离的临时钥匙串，并清理临时配置描述文件。它不会输出成功数据，因此 stdout 由子命令负责。切勿在命令中直接传入身份密码。

注意事项

• 务必检查 --help，以确认准确的枚举值（证书类型、配置描述文件类型）。
• 对大型帐户使用 --paginate。
• 需要多个证书时，--certificate 接受以逗号分隔的 ID。
• 设备管理使用 asc devices 命令（需要 UDID）。
• asc profiles inspect 和 asc profiles local ... 操作的是本地磁盘状态，而非 App Store Connect API 资源。