asc-workflow

asc workflow

次の場合に、CLI 内でレーン形式の自動化を行うスキルです。

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

ワークフローはリポジトリ内に置かれる自動化ファイルです。信頼できるシェルコマンドを実行し、ステップの出力を 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 <name>
• JSONC コメントがサポートされています。
• トップレベルのフック：before_all、after_all、error
• ワークフローのキー：description、private、env、steps
• ステップの形式：
  • 文字列の省略形式："echo hello"
  • run シェルコマンド
  • workflow サブワークフローの呼び出し
  • name ラベル
  • if 条件付き変数名
  • with ワークフロー呼び出しステップ用の環境変数の上書き
  • outputs 名前付き run ステップから JSON stdout を抽出するためのマップ
  • retry run ステップ用の固定遅延リトライポリシー
  • timeout run ステップ用の試行ごとの正の時間制限

出力

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

同じキーが繰り返された場合は、最後に指定した値が使われます。シェルコマンドでは、$VERSION のようなシェル展開を使ってパラメーターを参照してください。

環境変数の優先順位

メインワークフローの実行：

definition.env < workflow.env < CLI params

with を使ったサブワークフローの呼び出し：

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

条件分岐

ステップに "if": "VAR_NAME" を追加します。真と判定される値は 1、true、yes、y、on で、大文字と小文字は区別されません。参照時は、まずマージ済みのワークフロー環境変数／パラメーターを確認し、次にプロセス環境を確認します。

ワークフローの例

{
  "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-id $BUILD_ID --metadata-dir ./metadata --confirm --output json"
        },
        {
          "name": "submit",
          "if": "SUBMIT_FOR_REVIEW",
          "run": "asc review submit --app $APP_ID --version $VERSION --build-id $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 はコードとして扱い、信頼できるワークフローファイルのみを実行してください。
• シークレットを使って、信頼できない PR のワークフローを実行しないでください。
• ワークフローファイルはバージョン管理に含めてください。
• まず検証し、次にドライランを行い、その後に実行してください。
• 変更を伴うステップには、明示的な ID と --confirm を使用してください。
• asc validate、asc release stage、asc review submit、asc publish appstore を使用し、削除済みの提出コマンドは使用しないでください。