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"

請勿在 --resume 時傳遞額外的 KEY:VALUE 參數；會重複使用已儲存的工作流程檔案、參數和持續的輸出。

檔案位置與格式

• 預設路徑：.asc/workflow.json
• 覆寫路徑：asc workflow run --file ./path/to/workflow.json <名稱>
• 支援 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 <名稱> [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 參數

使用 with 的子工作流程呼叫：

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

條件

在步驟中加入 "if": "VAR_NAME"。真值為 1、true、yes、y 和 on，不區分大小寫。查詢會先檢查合併的工作流程 env/參數，然後檢查處理程序環境。

範例工作流程

{
  "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；請勿使用已移除的提交命令。