asc-workflow

asc workflow

當需要在 CLI 內使用 Channel / Lane 風格的自動化流程時，請使用此 Skill：

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

Workflow 是儲存庫本地的自動化設定檔。它們能執行可信的 Shell 指令，將步驟的輸出內容以 Stream 方式串流至 stderr，並保持 stdout 輸出為機器可讀的 JSON 格式。

指令探索 (Command discovery)

請務必使用以下指令確認參數標記（flags）：

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

完整端到端流程 (End-to-end flow)

1. 撰寫 .asc/workflow.json。
2. 驗證結構與引用設定：

asc workflow validate

3. 查看可用的公開 Workflow：

asc workflow list
asc workflow list --all

4. 預演執行（Preview execution）：

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 結果中的 Run ID 來恢復執行：

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

請勿在使用 --resume 時傳入額外的 KEY:VALUE 參數；系統會自動重用已儲存的 Workflow 檔案、參數與持久化的輸出內容。

檔案位置與格式 (File location and format)

• 預設路徑：.asc/workflow.json
• 覆蓋路徑：asc workflow run --file ./path/to/workflow.json <name>
• 支援 JSONC 註解。
• 頂層 Hook：before_all、after_all、error
• Workflow 欄位：description、private、env、steps
• 步驟（Step）撰寫形式：
  • 字串簡寫："echo hello"
  • run Shell 指令
  • workflow 子工作流呼叫
  • name 標籤名稱
  • if 條件變數名稱
  • with 針對子工作流呼叫步驟的環境變數覆蓋
  • outputs 映射表（用於從具名 run 步驟的 JSON stdout 提取內容）

輸出 (Outputs)

Run 步驟可以宣告輸出（outputs）。命令必須在 stdout 上輸出 JSON，因此對於會產生輸出的 asc 指令請傳入 --output json。

輸出引用格式如下：

${steps.step_name.OUTPUT_NAME}

規則：

• 宣告 outputs 的步驟必須具有符合引用安全規範的 name。
• 僅允許在 run 步驟上設定 Output，不支援 Workflow 呼叫步驟。
• 產生輸出的步驟名稱（Output-producing names）在同一個執行圖中可一起執行的 Workflow 之間必須是唯一的。
• 持久化的 Output 會儲存在 Workflow 執行狀態中，因此請勿將敏感資訊（secrets）映射至 Output 中。

執行階段參數 (Runtime params)

asc workflow run <name> [KEY:VALUE ...] 同時支援以下兩種分隔符號：

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

重複的 Key 以最後寫入者為準（last-write-wins）。在 Shell 指令中，可透過像 $VERSION 的 Shell 擴充語法來引用參數。

環境變數優先順序 (Env precedence)

主要 Workflow 執行：

definition.env < workflow.env < CLI 參數

使用 with 呼叫子工作流（Sub-workflow）：

子工作流 env < 呼叫者的 env 與參數 < 步驟的 with

條件判斷 (Conditionals)

在步驟中新增 "if": "VAR_NAME"。Truthy（真值）包含 1、true、yes、y 和 on（不分大小寫）。查找時會優先檢查合併後的 Workflow 環境變數／參數，接著才檢查處理程序環境變數（process environment）。

Workflow 範例 (Example workflow)

{
  "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 $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": "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"
        }
      ]
    }
  }
}

常用指令範例 (Useful invocations)

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"

安全規則 (Safety rules)

• 請將 .asc/workflow.json 視為程式碼看待；僅執行可信的 Workflow 檔案。
• 避免在包含機密資訊（secrets）的環境中執行來自不可信 PR 的 Workflow。
• 請將 Workflow 檔案納入版本控制。
• 遵循「先驗證，再預演，最後執行」的原則。
• 針對會變更狀態的步驟，使用明確的 ID 與 --confirm 參數。
• 請使用 asc validate、asc release stage、asc review submit 及 asc publish appstore；切勿使用已被廢棄或移除的提交指令。