rorkai/app-store-connect-cli-skills

asc ワークフロー

このスキルは、以下の asc CLI コマンドを使用して、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: 名前付き実行ステップからの 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 <name> [KEY:VALUE ...] は両方のセパレーターをサポートします。

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

重複するキーは最後に書き込まれたものが優先されます。シェルコマンドでは、$VERSION のようなシェル展開でパラメータを参照します。

環境変数の優先順位

メインワークフロー実行:

定義.env < ワークフロー.env < CLIパラメータ

with を使用したサブワークフロー呼び出し:

サブワークフロー.env < 呼び出し側.envとパラメータ < ステップのwith

条件

ステップに "if": "VAR_NAME" を追加します。真と評価される値は、大文字小文字を区別せずに 1、true、yes、y、on です。ルックアップは最初にマージされたワークフロー env/params をチェックし、次にプロセス環境をチェックします。

ワークフロー例

{
  "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 からシークレットを含むワークフローを実行しないでください。
• ワークフローファイルはバージョン管理に保持します。
• 最初に検証し、次に dry-run し、その後で実行します。
• 変更を行うステップには明示的な ID と --confirm を使用します。
• asc validate、asc release stage、asc review submit、asc publish appstore を使用します。削除された送信コマンドは使用しないでください。