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
   • 按需添加具体的 Capability 配置项：
     • --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 并不是完全可靠的过期判断依据：某些描述文件的 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

使用 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 类似的目录结构存储证书和描述文件。
• pull 命令仅将文件解密写入磁盘；导入 Keychain 或安装描述文件需执行后续步骤。

注意事项

• 请随时查看 --help 获取具体的枚举值（如证书类型、描述文件类型）。
• 针对大型账号，建议添加 --paginate 参数进行分页查询。
• 当需要关联多个证书时，--certificate 支持传入以逗号分隔的 ID 列表。
• 设备管理请使用 asc devices 系列命令（需提供 UDID）。
• asc profiles inspect 和 asc profiles local ... 操作的是本地磁盘状态，而非 App Store Connect API 资源。