rorkai/app-store-connect-cli-skills

asc-Workflow

Verwenden Sie dieses Skill, wenn Sie eine lane-ähnliche Automatisierung innerhalb der CLI benötigen, unter Verwendung von:

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

Workflows sind repo-lokale Automatisierungsdateien. Sie führen vertrauenswürdige Shell-Befehle aus, streamen Schritt-Ausgaben nach stderr und halten stdout als maschinenlesbares JSON.

Befehlsfindung

Überprüfen Sie immer die Flags mit:

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

End-to-End-Ablauf

1. Erstellen Sie .asc/workflow.json.
2. Validieren Sie Struktur und Referenzen:

asc workflow validate

3. Entdecken Sie öffentliche Workflows:

asc workflow list
asc workflow list --all

4. Vorschau der Ausführung:

asc workflow run --dry-run beta BUILD_ID:123456789 GROUP_ID:abcdef

5. Ausführen:

asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

6. Wenn ein wiederherstellbarer Lauf fehlschlägt, setzen Sie ihn mit der Lauf-ID aus dem JSON-Ergebnis fort:

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

Übergeben Sie keine zusätzlichen SCHLÜSSEL:WERT-Parameter mit --resume; die gespeicherte Workflow-Datei, Parameter und beibehaltenen Ausgaben werden wiederverwendet.

Dateipfad und -format

• Standardpfad: .asc/workflow.json
• Überschreibungspfad: asc workflow run --file ./path/to/workflow.json <name>
• JSONC-Kommentare werden unterstützt.
• Top-Level-Hooks: before_all, after_all, error
• Workflow-Schlüssel: description, private, env, steps
• Schritt-Formen:
  • String-Kurzform: "echo hello"
  • run Shell-Befehl
  • workflow Sub-Workflow-Aufruf
  • name Bezeichnung
  • if Bedingungsvariablenname
  • with Umgebungsüberschreibungen für Workflow-Call-Schritte
  • outputs Map für JSON-stdout-Extraktion aus benannten Run-Schritten
  • retry Wiederholungsrichtlinie mit fester Verzögerung für einen run-Schritt
  • timeout positive Dauer pro Versuch für einen run-Schritt

Ausgaben

Run-Schritte können Ausgaben deklarieren. Der Befehl muss JSON auf stdout ausgeben. Übergeben Sie daher --output json für asc-Befehle, die Ausgaben erzeugen.

Ausgabereferenzen verwenden:

${steps.step_name.OUTPUT_NAME}

Regeln:

• Ein Schritt, der outputs deklariert, muss einen referenzsicheren name haben.
• Ausgaben sind nur für run-Schritte erlaubt, nicht für Workflow-Call-Schritte.
• Namen, die Ausgaben erzeugen, müssen über Workflows hinweg eindeutig sein, die im selben Laufgraphen ausgeführt werden können.
• Beibehaltene Ausgaben werden im Workflow-Laufzustand gespeichert. Ordnen Sie daher keine Geheimnisse in Ausgaben ab.

Begrenzte Wiederholungen und Timeout

Fügen Sie Wiederholungen nur zu Befehlen hinzu, von denen Sie sicher sind, dass sie wiederholt werden können. Der Runner klassifiziert keine Befehle oder wiederholt Mutationen eigenständig.

{
  "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 zählt den ersten Versuch und muss zwischen 2 und 100 liegen. Wiederholungsverzögerungen und Timeouts müssen positive Dauern von höchstens 24 Stunden sein. Beide Felder funktionieren nur bei run-Schritten, nicht bei Workflow-Aufrufen oder Lifecycle-Hooks.

Ein Timeout ohne Wiederholung ist endgültig, da der Befehl möglicherweise remote abgeschlossen wurde. Das Paaren von Wiederholung und Timeout ist das explizite Signal, dass ein weiterer Versuch sicher ist. Die Wiederaufnahme erfordert entweder einen erfolgreichen Checkpoint oder einen fehlgeschlagenen Schritt mit aktivierter Wiederholung; Fehler bei der Ausgabeextraktion können nicht wieder aufgenommen werden.

Laufzeitparameter

asc workflow run <name> [KEY:VALUE ...] unterstützt beide Trennzeichen:

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

Wiederholte Schlüssel werden nach dem Last-Write-Prinzip behandelt. In Shell-Befehlen referenzieren Sie Parameter durch Shell-Expansion wie $VERSION.

Umgebungs-Priorität

Haupt-Workflow-Lauf:

definition.env < workflow.env < CLI-Parameter

Sub-Workflow-Aufruf mit with:

Sub-Workflow-Umgebung < Aufrufer-Umgebung und -Parameter < mit-Schritt

Bedingungen

Fügen Sie "if": "VAR_NAME" zu einem Schritt hinzu. Wahrheitswerte sind 1, true, yes, y und on, case-insensitiv. Die Suche prüft zuerst die zusammengeführte Workflow-Umgebung/Parameter, dann die Prozessumgebung.

Beispiel-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": "Löse den neuesten Build auf und verteile ihn an 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": "Validieren, Stagen und Einreichen einer 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": "Hochladen plus App Store-Review-Einreichung auf hoher Ebene",
      "steps": [
        {
          "name": "publish",
          "run": "asc publish appstore --app $APP_ID --ipa ./build/MyApp.ipa --version $VERSION --wait --submit --confirm --output json"
        }
      ]
    }
  }
}

Nützliche Aufrufe

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"

Sicherheitsregeln

• Behandeln Sie .asc/workflow.json wie Code; führen Sie nur vertrauenswürdige Workflow-Dateien aus.
• Vermeiden Sie die Ausführung von Workflows aus nicht vertrauenswürdigen PRs mit Geheimnissen.
• Halten Sie Workflow-Dateien unter Versionskontrolle.
• Validieren Sie zuerst, führen Sie einen Trockenlauf durch, dann führen Sie aus.
• Verwenden Sie explizite IDs und --confirm für mutierende Schritte.
• Verwenden Sie asc validate, asc release stage, asc review submit und asc publish appstore; verwenden Sie keine entfernten Einreichungsbefehle.