Back to Details

asc-xcode-cloud

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Xcode Cloud with 
asc

使用
asc
操作Xcode Cloud

Manage Xcode Cloud products, workflows, and build runs through the App Store Connect API.
通过App Store Connect API管理Xcode Cloud的产品、工作流和构建运行记录。

Authentication

认证

bash
asc auth login --key-id <id> --issuer-id <id> --private-key-path ~/.asc/AuthKey.p8
bash
asc auth login --key-id <id> --issuer-id <id> --private-key-path ~/.asc/AuthKey.p8

How to Navigate (CAEOAS Affordances)

操作导航（CAEOAS 功能入口）

Every JSON response contains an 
"affordances"
field with ready-to-run commands — IDs already filled in. This means you never need to remember or copy-paste IDs manually: just run the command from the affordance of the previous response.
For example, after listing products, the response tells you exactly what to run next:
json
{
  "id": "prod-abc123",
  "name": "My App",
  "affordances": {
    "listWorkflows": "asc xcode-cloud workflows list --product-id prod-abc123"
  }
}
And after listing workflows, the 
startBuild
affordance appears — but only when the workflow is enabled. If 
startBuild
is missing, the workflow is disabled (
isEnabled: false
) and cannot be triggered.
json
{
  "id": "wf-xyz",
  "name": "CI Build",
  "isEnabled": true,
  "affordances": {
    "startBuild": "asc xcode-cloud builds start --workflow-id wf-xyz",
    "listBuildRuns": "asc xcode-cloud builds list --workflow-id wf-xyz"
  }
}
每个JSON响应都包含一个
"affordances"
字段，其中包含可直接运行的命令——ID已自动填充。这意味着您无需手动记忆或复制粘贴ID：只需运行上一个响应中affordance提供的命令即可。
例如，列出产品后，响应会明确告知您下一步该运行的命令：
json
{
  "id": "prod-abc123",
  "name": "My App",
  "affordances": {
    "listWorkflows": "asc xcode-cloud workflows list --product-id prod-abc123"
  }
}
而在列出工作流后，会出现
startBuild
功能入口——但仅当工作流处于启用状态时才会显示。如果
startBuild
不存在，则说明该工作流已禁用（
isEnabled: false
），无法触发构建。
json
{
  "id": "wf-xyz",
  "name": "CI Build",
  "isEnabled": true,
  "affordances": {
    "startBuild": "asc xcode-cloud builds start --workflow-id wf-xyz",
    "listBuildRuns": "asc xcode-cloud builds list --workflow-id wf-xyz"
  }
}

Typical Workflows

典型工作流

Trigger a build (step by step)

触发构建（分步操作）

bash
undefined
bash
undefined

1. Find the Xcode Cloud product for your app

1. 查找对应应用的Xcode Cloud产品

asc xcode-cloud products list --app-id 6443417124 --pretty
asc xcode-cloud products list --app-id 6443417124 --pretty

2. Copy the listWorkflows affordance from the response and run it

2. 复制响应中的listWorkflows命令并运行

asc xcode-cloud workflows list --product-id prod-abc123 --pretty
asc xcode-cloud workflows list --product-id prod-abc123 --pretty

3. Copy the startBuild affordance from the workflow you want and run it

3. 复制目标工作流中的startBuild命令并运行

asc xcode-cloud builds start --workflow-id wf-xyz --pretty

Or as a script:

```bash
PRODUCT_ID=$(asc xcode-cloud products list --app-id APP_ID | jq -r '.data[0].id')
WORKFLOW_ID=$(asc xcode-cloud workflows list --product-id "$PRODUCT_ID" \
  | jq -r '.data[] | select(.name == "CI Build") | .id')
asc xcode-cloud builds start --workflow-id "$WORKFLOW_ID"
asc xcode-cloud builds start --workflow-id wf-xyz --pretty

或编写为脚本：

```bash
PRODUCT_ID=$(asc xcode-cloud products list --app-id APP_ID | jq -r '.data[0].id')
WORKFLOW_ID=$(asc xcode-cloud workflows list --product-id "$PRODUCT_ID" \
  | jq -r '.data[] | select(.name == "CI Build") | .id')
asc xcode-cloud builds start --workflow-id "$WORKFLOW_ID"

Check build status

检查构建状态

bash
asc xcode-cloud builds get --build-run-id run-99 --pretty
Look at 
executionProgress
first: if it's 
COMPLETE
, check 
completionStatus
to see if it passed or failed.
bash
asc xcode-cloud builds get --build-run-id run-99 --pretty
首先查看
executionProgress
字段：如果值为
COMPLETE
，再检查
completionStatus
以确认构建是通过还是失败。

See recent builds at a glance

快速查看近期构建记录

bash
asc xcode-cloud builds list --workflow-id wf-xyz --output table
bash
asc xcode-cloud builds list --workflow-id wf-xyz --output table

Clean build (clears derived data)

清理构建（清除派生数据）

bash
asc xcode-cloud builds start --workflow-id wf-xyz --clean
bash
asc xcode-cloud builds start --workflow-id wf-xyz --clean

Reading Build Results

解读构建结果

executionProgress
 — where is the build now?
ValueMeaning
PENDING
Queued, not started yet
RUNNING
Actively building
COMPLETE
Done — check 
completionStatus
completionStatus
 — did it succeed? (only set when 
COMPLETE
)
ValueMeaning
hasFailed
SUCCEEDED
All actions passedfalse
FAILED
One or more actions failedtrue
ERRORED
Infrastructure/system errortrue
CANCELED
Manually cancelledfalse
SKIPPED
Build was skippedfalse
executionProgress
 —— 当前构建处于哪个阶段？
值含义
PENDING
已排队，尚未开始
RUNNING
正在构建中
COMPLETE
已完成——请查看
completionStatus
completionStatus
 —— 构建是否成功？（仅当
executionProgress
为
COMPLETE
时才会设置）
值含义
hasFailed
SUCCEEDED
所有步骤均通过false
FAILED
一个或多个步骤失败true
ERRORED
基础设施/系统错误true
CANCELED
手动取消false
SKIPPED
构建被跳过false

Full Command Reference

完整命令参考

See commands.md for all flags and examples.
查看commands.md获取所有参数和示例。