asc-workflow

asc workflow

當你需要透過 CLI 進行泳道式（lane-style）自動化流程時，請使用此 Skill，相關指令包括：

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

工作流程（Workflow）是存於專案本地的自動化設定檔。它們會執行可信賴的 Shell 指令，將步驟輸出串流至 stderr，並將 stdout 保留為機器可讀的 JSON 格式。

指令探索

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

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 結果中的 run 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 註解語法。
• 頂層 Hook：before_all、after_all、error
• 工作流程 Key：description、private、env、steps
• 步驟定義形式：
  • 字串簡寫："echo hello"
  • run：Shell 指令
  • workflow：子工作流程呼叫
  • name：標籤名稱
  • if：條件式變數名稱
  • with：專為呼叫子工作流程設定的環境變數覆寫
  • outputs：從具名 run 步驟提取 JSON stdout 的映射設定

步驟輸出

run 步驟可以宣告 outputs。該指令必須在 stdout 輸出 JSON 內容，因此若執行會產生輸出的 asc 指令，請傳入 --output json。

引用輸出的語法格式：

${steps.step_name.OUTPUT_NAME}

規則：

• 宣告 outputs 的步驟，必須具備合乎引用規範的 name。
• 僅允許在 run 步驟中定義 output，子工作流程呼叫步驟則不支援。
• 在同一執行圖（run graph）中可能一同執行的工作流程之間，產生 output 的步驟名稱必須保持唯一。
• 持久化的輸出會儲存於工作流程的執行狀態（run state）中，請勿將敏感資訊（secrets）映射至 output。

執行期參數

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 展開語法來引用參數。

環境變數優先順序

主工作流程執行：

definition.env < workflow.env < CLI params

使用 with 呼叫子工作流程：

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

條件判斷

在步驟中加入 "if": "VAR_NAME"。不區分大小寫的情況下，真值（Truthy values）包括 1、true、yes、y 與 on。搜尋順序會先檢查合併後的工作流程環境變數與參數，接著才檢查行程環境變數（process environment）。

工作流程範例

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

常用指令範例

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 視同程式碼處理；僅執行可信賴的工作流程檔案。
• 避免在含有敏感資訊（secrets）的環境下執行來自不可信 PR 的工作流程。
• 請將工作流程檔案納入版本控制（version control）。
• 遵循「先驗證（validate）、再預覽（dry-run）、最後執行（run）」的原則。
• 針對會變更狀態的步驟，使用明確的 ID 與 --confirm 標誌。
• 請使用 asc validate、asc release stage、asc review submit 與 asc publish appstore；切勿使用已被廢棄的提交指令。