rorkai/app-store-connect-cli-skills

asc 工作流

如果您需要使用 CLI 实现 lane 式自动化，请使用本技能，涉及命令包括：

• 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"

不要将额外的 KEY:VALUE 参数与 --resume 一起传递；保存的工作流文件、参数和持久化输出将被重用。

文件位置与格式

• 默认路径：.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 从已命名运行步骤中提取 JSON stdout 的映射
  • retry 为 run 步骤设置固定延迟重试策略
  • timeout 为 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 命令中，通过 shell 扩展（如 $VERSION）引用参数。

环境变量优先级

主工作流运行：

definition.env < workflow.env < CLI params

带 with 的子工作流调用：

子工作流 env < 调用者 env 和 params < 步骤 with

条件执行

向步骤添加 "if": "VAR_NAME"。真值包括 1、true、yes、y、on，不区分大小写。查找首先检查合并的工作流 env/params，然后检查进程环境。

示例工作流

{
  "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": "解析最新构建并分发到 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": "验证、暂存并提交 App Store 版本",
      "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 $BUILD_ID --metadata-dir ./metadata/version/$VERSION --confirm --output json"
        },
        {
          "name": "submit",
          "if": "SUBMIT_FOR_REVIEW",
          "run": "asc review submit --app $APP_ID --version $VERSION --build $BUILD_ID --confirm --output json"
        }
      ]
    },
    "publish-appstore": {
      "description": "高级上传与 App Store 审核提交",
      "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；不要使用已废弃的提交命令。