asc-workflow

asc workflow

当你需要在 CLI 中使用类似流水线的自动化时，请使用此技能：

• asc workflow validate
• asc workflow list
• asc workflow run

工作流是仓库本地的自动化文件。它们会运行受信任的 shell 命令，将步骤输出流式写入 stderr，并将 stdout 保持为机器可读的 JSON。

命令查询

始终使用以下命令确认标志：

asc workflow --help
asc workflow validate --help
asc workflow list --help
asc workflow run --help

端到端流程

1. 编写 .asc/workflow.json。
2. 验证结构和引用：

asc workflow validate

3. 查询公开工作流：

asc workflow list
asc workflow list --all

4. 预览执行过程：

asc workflow run --dry-run beta BUILD_ID:123456789 GROUP_ID:abcdef

5. 执行：

asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

6. 如果某次运行因可恢复的问题失败，请使用 JSON 结果中的运行 ID 恢复：

asc workflow run release --resume "release-20260312T120000Z-deadbeef"

使用 --resume 时不要传入额外的 KEY:VALUE 参数；系统会复用已保存的工作流文件、参数和持久化输出。

文件位置和格式

• 默认路径：.asc/workflow.json
• 覆盖路径：asc workflow run --file ./path/to/workflow.json <name>
• 支持 JSONC 注释。
• 顶层钩子：before_all、after_all、error
• 工作流键：description、private、env、steps
• 步骤形式：
  • 字符串简写："echo hello"
  • run shell 命令
  • workflow 子工作流调用
  • name 标签
  • if 条件变量名
  • with 工作流调用步骤的环境变量覆盖项
  • outputs 映射，用于从已命名的 run 步骤的 JSON stdout 中提取内容
  • retry，用于 run 步骤的固定延迟重试策略
  • timeout，用于 run 步骤的单次尝试时长，必须为正值

输出

run 步骤可以声明输出。命令必须在 stdout 上输出 JSON，因此对于会产生输出的 asc 命令，请传入 --output json。

输出引用使用：

${steps.step_name.OUTPUT_NAME}

规则：

• 声明了 outputs 的步骤必须具有可安全用于引用的 name。
• 输出只能用于 run 步骤，不能用于工作流调用步骤。
• 在同一次运行图中可能共同执行的工作流之间，产生输出的名称必须唯一。
• 持久化输出会存储在工作流运行状态中，因此不要将机密映射到输出中。

有限重试和超时

只有在确认命令可安全重复执行后，才添加重试。运行器不会自行对命令进行分类，也不会自行重试变更操作。

{
  "name": "resolve_build",
  "run": "asc builds info --app $APP_ID --latest --platform IOS --output json",
  "retry": {
    "max_attempts": 3,
    "delay": "5s"
  },
  "timeout": "2m"
}

retry.max_attempts 计算首次尝试，必须介于 2 和 100 之间。重试延迟和超时必须为正值，且不超过 24 小时。这两个字段只能用于 run 步骤，不能用于工作流调用或生命周期钩子。

没有重试的超时会导致运行终止，因为命令可能已在远程端完成。将重试与超时配合使用，明确表示可以再次尝试。恢复运行需要成功的检查点，或启用了重试但失败的步骤；无法恢复输出提取失败。

运行时参数

asc workflow run <name> [KEY:VALUE ...] 支持以下两种分隔符：

asc workflow run beta VERSION:2.1.0
asc workflow run beta VERSION=2.1.0

重复的键以后写入的值为准。在 shell 命令中，通过 $VERSION 这类 shell 展开方式引用参数。

环境变量优先级

主工作流运行：

definition.env < workflow.env < CLI params

带有 with 的子工作流调用：

sub-workflow env < caller env and params < step with

条件语句

向步骤添加 "if": "VAR_NAME"。真值包括 1、true、yes、y 和 on，且不区分大小写。查找时会先检查合并后的工作流环境变量和参数，然后检查进程环境。

工作流示例

{
  "env": {
    "APP_ID": "123456789",
    "VERSION": "1.0.0",
    "GROUP_ID": ""
  },
  "before_all": "asc auth status",
  "after_all": "echo workflow_done",
  "error": "echo workflow_failed",
  "workflows": {
    "beta": {
      "description": "Resolve the latest build and distribute it to TestFlight",
      "steps": [
        {
          "name": "resolve_build",
          "run": "asc builds info --app $APP_ID --latest --platform IOS --output json",
          "outputs": {
            "BUILD_ID": "$.data.id"
          }
        },
        {
          "name": "list_groups",
          "run": "asc testflight groups list --app $APP_ID --limit 20 --output json"
        },
        {
          "name": "add_build_to_group",
          "if": "GROUP_ID",
          "run": "asc builds add-groups --build-id ${steps.resolve_build.BUILD_ID} --group $GROUP_ID"
        }
      ]
    },
    "release": {
      "description": "Validate, stage, and submit an App Store version",
      "steps": [
        {
          "name": "validate",
          "run": "asc validate --app $APP_ID --version $VERSION --platform IOS --output json"
        },
        {
          "name": "stage",
          "run": "asc release stage --app $APP_ID --version $VERSION --build-id $BUILD_ID --metadata-dir ./metadata --confirm --output json"
        },
        {
          "name": "submit",
          "if": "SUBMIT_FOR_REVIEW",
          "run": "asc review submit --app $APP_ID --version $VERSION --build-id $BUILD_ID --confirm --output json"
        }
      ]
    },
    "publish-appstore": {
      "description": "High-level upload plus App Store review submission",
      "steps": [
        {
          "name": "publish",
          "run": "asc publish appstore --app $APP_ID --ipa ./build/MyApp.ipa --version $VERSION --wait --submit --confirm --output json"
        }
      ]
    }
  }
}

常用调用

asc workflow validate | jq -e '.valid == true'
asc workflow list --pretty
asc workflow list --all --pretty
asc workflow run --dry-run beta BUILD_ID:123 GROUP_ID:grp_abc
asc workflow run beta BUILD_ID:123 GROUP_ID:grp_abc | jq -e '.status == "ok"'
asc workflow run release BUILD_ID:123 SUBMIT_FOR_REVIEW:true
asc workflow run release --resume "release-20260312T120000Z-deadbeef"

安全规则

• 将 .asc/workflow.json 视为代码；仅运行受信任的工作流文件。
• 避免在包含机密的情况下运行来自不受信任 PR 的工作流。
• 将工作流文件纳入版本控制。
• 先验证，再试运行，最后运行。
• 对变更步骤使用显式 ID 和 --confirm。
• 使用 asc validate、asc release stage、asc review submit 和 asc publish appstore；不要使用已移除的提交命令。