asc-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

asc workflow

Use this skill when you need lane-style automation inside the CLI using:

```
asc workflow run
```
```
asc workflow validate
```
```
asc workflow list
```

This feature is best for deterministic automation that lives in your repo, is reviewable in PRs, and can run the same way locally and in CI.

当你需要在CLI中实现lane风格的自动化时，可以使用该功能，涉及以下命令：

```
asc workflow run
```
```
asc workflow validate
```
```
asc workflow list
```

该功能最适合用于确定性的自动化流程，这类流程存储在你的仓库中，可在PR中进行评审，并且能在本地和CI环境中以相同方式运行。

Command discovery

命令探索

Always use

--help

to confirm flags and subcommands:

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

始终使用

--help

来确认可用的标志和子命令：

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

End-to-end flow

端到端流程

Author
```
.asc/workflow.json
```
Validate structure and references:
- ```
asc workflow validate
```
Discover available workflows:
- ```
asc workflow list
```
- ```
asc workflow list --all
```
  (includes private helpers)
Preview execution without side effects:
- ```
asc workflow run --dry-run beta
```

Execute with runtime params:

asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

编写
```
.asc/workflow.json
```
文件
验证文件结构和引用：
- ```
asc workflow validate
```
查看可用的工作流：
- ```
asc workflow list
```
- ```
asc workflow list --all
```
  （包含私有辅助工作流）
预执行以预览效果，无实际副作用：
- ```
asc workflow run --dry-run beta
```

传入运行时参数执行：

asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

File location and format

文件位置与格式

Default path:
```
.asc/workflow.json
```

Override path:

asc workflow run --file ./path/to/workflow.json <name>

JSONC comments are supported (
```
//
```
and
```
/* ... */
```
)

默认路径：
```
.asc/workflow.json
```

覆盖路径：

asc workflow run --file ./path/to/workflow.json <name>

支持JSONC注释（
```
//
```
和
```
/* ... */
```
）

Output and CI contract

输出与CI约定

```
stdout
```
: structured JSON result (
```
status
```
,
```
steps
```
, durations)
```
stderr
```
: step command output, hook output, dry-run previews
```
asc workflow validate
```
always prints JSON and returns non-zero when invalid

This enables machine-safe checks:

bash

asc workflow validate | jq -e '.valid == true'
asc workflow run beta BUILD_ID:123 GROUP_ID:xyz | jq -e '.status == "ok"'

```
stdout
```
：结构化JSON结果（包含
```
status
```
、
```
steps
```
、执行时长）
```
stderr
```
：步骤命令输出、钩子输出、预执行预览内容
```
asc workflow validate
```
始终输出JSON格式，当文件无效时返回非零状态码

这使得机器可安全地进行校验：

bash

asc workflow validate | jq -e '.valid == true'
asc workflow run beta BUILD_ID:123 GROUP_ID:xyz | jq -e '.status == "ok"'

Schema (what the feature supports)

Schema（功能支持的内容）

Top-level keys:

```
env
```
: global defaults
```
before_all
```
: command run once before steps
```
after_all
```
: command run once after successful steps
```
error
```
: command run when any failure occurs
```
workflows
```
: named workflow map

Workflow keys:

```
description
```
```
private
```
(not directly runnable)
```
env
```
```
steps
```

Step forms:

String shorthand:
```
"echo hello"
```
-> run step
Object with:
- ```
run
```
  : shell command
- ```
workflow
```
  : call sub-workflow
- ```
name
```
  : label for reporting
- ```
if
```
  : conditional var name
- ```
with
```
  : env overrides for workflow-call steps only

顶级键：

```
env
```
：全局默认环境变量
```
before_all
```
：在步骤执行前运行一次的命令
```
after_all
```
：在所有步骤成功执行后运行一次的命令
```
error
```
：当任何步骤失败时运行的命令
```
workflows
```
：命名工作流的映射表

工作流键：

```
description
```
：描述信息
```
private
```
（不可直接运行）
```
env
```
：工作流专属环境变量
```
steps
```
：工作流步骤

步骤形式：

字符串简写形式：
```
"echo hello"
```
-> 运行该步骤
对象形式包含以下字段：
- ```
run
```
  ：Shell命令
- ```
workflow
```
  ：调用子工作流
- ```
name
```
  ：用于报告的步骤名称
- ```
if
```
  ：条件变量名称
- ```
with
```
  ：仅在调用子工作流的步骤中生效的环境变量覆盖配置

Runtime params (

KEY:VALUE

KEY=VALUE

)

运行时参数（

KEY:VALUE

KEY=VALUE

）

asc workflow run <name> [KEY:VALUE ...]

supports both separators:

```
VERSION:2.1.0
```
```
VERSION=2.1.0
```

If both separators exist, the first one wins.
Repeated keys are last-write-wins.
In step commands, reference params via shell expansion (
```
$VAR
```
).
Avoid putting secrets in
```
.asc/workflow.json
```
; pass them via CI secrets/env.

asc workflow run <name> [KEY:VALUE ...]

支持两种分隔符：

```
VERSION:2.1.0
```
```
VERSION=2.1.0
```

如果同时存在两种分隔符，以第一个为准
重复的参数键以最后一次赋值为准
在步骤命令中，通过Shell变量展开（
```
$VAR
```
）来引用参数
避免在
```
.asc/workflow.json
```
中存储敏感信息；请通过CI的环境变量或机密传递

Run-tail flags

后置运行标志

asc workflow run

also accepts core flags after the workflow name:

```
--dry-run
```
```
--pretty
```
```
--file
```

Examples:

```
asc workflow run beta --dry-run
```

asc workflow run beta --file .asc/workflow.json BUILD_ID:123

asc workflow run

还支持在工作流名称后添加核心标志：

```
--dry-run
```
```
--pretty
```
```
--file
```

示例：

```
asc workflow run beta --dry-run
```

asc workflow run beta --file .asc/workflow.json BUILD_ID:123

Execution semantics

执行语义

```
before_all
```
runs once before step execution
```
after_all
```
runs only when steps succeed
```
error
```
runs on failure (step failure, before/after hook failure)
Sub-workflows are executed inline as part of the call step
Maximum sub-workflow nesting depth is 16

```
before_all
```
在步骤执行前仅运行一次
```
after_all
```
仅在所有步骤成功执行后运行
```
error
```
在出现失败时运行（步骤失败、前置/后置钩子失败）
子工作流会作为调用步骤的一部分内联执行
子工作流的最大嵌套深度为16层

Env precedence

环境变量优先级

Main workflow run:

```
definition.env
```
<
```
workflow.env
```
< CLI params

Sub-workflow call step (

"workflow": "...", "with": {...}

sub-workflow
```
env
```
defaults
caller env (including CLI params) overrides
step
```
with
```
overrides all

主工作流运行时：

```
definition.env
```
<
```
workflow.env
```
< CLI参数

子工作流调用步骤（

"workflow": "...", "with": {...}

）：

子工作流的
```
env
```
默认值
调用方的环境变量（包括CLI参数）会覆盖默认值
步骤的
```
with
```
配置会覆盖所有上述值

Sub-workflows and private workflows

子工作流与私有工作流

Use
```
"workflow": "<name>"
```
to call helper workflows.
Use
```
"private": true
```
for helper-only workflows.
Private workflows:
- cannot be run directly
- can be called by other workflows
- are hidden from
```
asc workflow list
```
  unless
```
--all
```
  is used
Validation catches unknown workflow references and cyclic references.

使用
```
"workflow": "<name>"
```
来调用辅助工作流
使用
```
"private": true
```
标记仅作为辅助使用的工作流
私有工作流：
- 无法直接运行
- 可被其他工作流调用
- 在
```
asc workflow list
```
  中默认隐藏，除非使用
```
--all
```
  参数
验证过程会检测未知的工作流引用和循环引用

Conditionals (

if

)

条件判断（

if

）

Add
```
"if": "VAR_NAME"
```
on a step.
Step runs only if
```
VAR_NAME
```
is truthy.
Truthy:
```
1
```
,
```
true
```
,
```
yes
```
,
```
y
```
,
```
on
```
(case-insensitive).
Resolution order for
```
if
```
lookup:
1. merged workflow env/params
2. ```
os.Getenv(VAR_NAME)
```

在步骤中添加
```
"if": "VAR_NAME"
```
配置
仅当
```
VAR_NAME
```
为真值时，该步骤才会运行
真值包括：
```
1
```
、
```
true
```
、
```
yes
```
、
```
y
```
、
```
on
```
（不区分大小写）
```
if
```
变量的查找顺序：
1. 合并后的工作流环境变量/参数
2. ```
os.Getenv(VAR_NAME)
```
  （系统环境变量）

Dry-run behavior

预执行（Dry-run）行为

```
asc workflow run --dry-run <name>
```
does not execute commands.
It prints previews to
```
stderr
```
.
Dry-run shows raw commands (without env expansion), which helps avoid secret leakage in previews.

```
asc workflow run --dry-run <name>
```
不会实际执行命令
会将预览内容输出到
```
stderr
```
预执行会显示原始命令（不进行环境变量展开），有助于避免在预览中泄露敏感信息

Shell behavior

Shell行为

Run steps use
```
bash -o pipefail -c
```
when bash is available.
Fallback is
```
sh -c
```
when bash is unavailable.
Pipelines therefore fail correctly in most CI shells when bash exists.

当系统存在bash时，步骤会使用
```
bash -o pipefail -c
```
来执行
当bash不可用时，会回退到
```
sh -c
```
因此，在大多数CI Shell中，如果存在bash，流水线会正确地在失败时终止

Practical authoring rules

实用编写规则

Keep workflow files in version control.
Use IDs in step commands where possible for deterministic automation.
Use
```
--confirm
```
for destructive
```
asc
```
operations inside steps.
Validate first, then dry-run, then real run.
Keep hooks lightweight and side-effect aware.

json

{
  "env": {
    "APP_ID": "123456789",
    "VERSION": "1.0.0"
  },
  "before_all": "asc auth status",
  "after_all": "echo workflow_done",
  "error": "echo workflow_failed",
  "workflows": {
    "beta": {
      "description": "Distribute a build to a TestFlight group and notify",
      "env": {
        "GROUP_ID": ""
      },
      "steps": [
        {
          "name": "list_builds",
          "run": "asc builds list --app $APP_ID --sort -uploadedDate --limit 5"
        },
        {
          "name": "list_groups",
          "run": "asc testflight beta-groups list --app $APP_ID --limit 20"
        },
        {
          "name": "add_build_to_group",
          "if": "BUILD_ID",
          "run": "asc builds add-groups --build $BUILD_ID --group $GROUP_ID"
        },
        {
          "name": "notify",
          "if": "SLACK_WEBHOOK",
          "run": "echo sent_release_notice"
        }
      ]
    },
    "release": {
      "description": "Submit a version for App Store review",
      "steps": [
        {
          "workflow": "sync-metadata",
          "with": {
            "METADATA_DIR": "./metadata"
          }
        },
        {
          "name": "submit",
          "run": "asc submit create --app $APP_ID --version $VERSION --build $BUILD_ID --confirm"
        }
      ]
    },
    "sync-metadata": {
      "private": true,
      "description": "Private helper workflow (callable only via workflow steps)",
      "steps": [
        {
          "name": "migrate_validate",
          "run": "echo METADATA_DIR_is_$METADATA_DIR"
        }
      ]
    }
  }
}

将工作流文件纳入版本控制
尽可能在步骤命令中使用ID，以实现确定性的自动化
在步骤中执行具有破坏性的
```
asc
```
操作时，使用
```
--confirm
```
参数
先验证，再预执行，最后实际运行
保持钩子轻量化，并注意其副作用

json

{
  "env": {
    "APP_ID": "123456789",
    "VERSION": "1.0.0"
  },
  "before_all": "asc auth status",
  "after_all": "echo workflow_done",
  "error": "echo workflow_failed",
  "workflows": {
    "beta": {
      "description": "Distribute a build to a TestFlight group and notify",
      "env": {
        "GROUP_ID": ""
      },
      "steps": [
        {
          "name": "list_builds",
          "run": "asc builds list --app $APP_ID --sort -uploadedDate --limit 5"
        },
        {
          "name": "list_groups",
          "run": "asc testflight beta-groups list --app $APP_ID --limit 20"
        },
        {
          "name": "add_build_to_group",
          "if": "BUILD_ID",
          "run": "asc builds add-groups --build $BUILD_ID --group $GROUP_ID"
        },
        {
          "name": "notify",
          "if": "SLACK_WEBHOOK",
          "run": "echo sent_release_notice"
        }
      ]
    },
    "release": {
      "description": "Submit a version for App Store review",
      "steps": [
        {
          "workflow": "sync-metadata",
          "with": {
            "METADATA_DIR": "./metadata"
          }
        },
        {
          "name": "submit",
          "run": "asc submit create --app $APP_ID --version $VERSION --build $BUILD_ID --confirm"
        }
      ]
    },
    "sync-metadata": {
      "private": true,
      "description": "Private helper workflow (callable only via workflow steps)",
      "steps": [
        {
          "name": "migrate_validate",
          "run": "echo METADATA_DIR_is_$METADATA_DIR"
        }
      ]
    }
  }
}

Useful invocations

常用调用示例

bash

undefined

bash

undefined

Validate and fail CI on invalid file

验证文件有效性，若无效则终止CI流程

asc workflow validate | jq -e '.valid == true'

Show discoverable workflows

显示可发现的工作流

asc workflow list --pretty

Include private helpers

包含私有辅助工作流

asc workflow list --all --pretty

Preview a real run

预览实际运行效果

asc workflow run --dry-run beta BUILD_ID:123 GROUP_ID:grp_abc

Run with params and assert success

传入参数运行并断言执行成功

asc workflow run beta BUILD_ID:123 GROUP_ID:grp_abc | jq -e '.status == "ok"'

undefined

asc workflow run beta BUILD_ID:123 GROUP_ID:grp_abc | jq -e '.status == "ok"'

undefined

asc-workflow

Original

Translation

asc workflow

asc workflow

Command discovery

命令探索

End-to-end flow

端到端流程

File location and format

文件位置与格式

Output and CI contract

输出与CI约定

Schema (what the feature supports)

Schema（功能支持的内容）

Runtime params (KEY:VALUE / KEY=VALUE)

运行时参数（KEY:VALUE / KEY=VALUE）

Run-tail flags

后置运行标志

Execution semantics

执行语义

Env precedence

环境变量优先级

Sub-workflows and private workflows

子工作流与私有工作流

Conditionals (if)

条件判断（if）

Dry-run behavior

预执行（Dry-run）行为

Shell behavior

Shell行为

Practical authoring rules

实用编写规则

Useful invocations

常用调用示例

Validate and fail CI on invalid file

验证文件有效性，若无效则终止CI流程

Show discoverable workflows

显示可发现的工作流

Include private helpers

包含私有辅助工作流

Preview a real run

预览实际运行效果

Run with params and assert success

传入参数运行并断言执行成功

Runtime params (
`KEY:VALUE`
/
`KEY=VALUE`
)

运行时参数（
`KEY:VALUE`
/
`KEY=VALUE`
）

Conditionals (
`if`
)

条件判断（
`if`
）