rorkai/app-store-connect-cli-skills

workflow asc

Utilisez cette compétence lorsque vous avez besoin d'une automatisation de type lanes dans le CLI à l'aide de :

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

Les workflows sont des fichiers d'automatisation locaux au dépôt. Ils exécutent des commandes shell de confiance, diffusent la sortie des étapes sur stderr et conservent stdout comme JSON lisible par machine.

Découverte des commandes

Vérifiez toujours les options avec :

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

Flux de bout en bout

1. Créez .asc/workflow.json.
2. Validez la structure et les références :

asc workflow validate

3. Découvrez les workflows publics :

asc workflow list
asc workflow list --all

4. Prévisualisez l'exécution :

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

5. Exécutez :

asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

6. Si une exécution récupérable échoue, reprenez avec l'ID d'exécution du résultat JSON :

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

Ne passez pas de paramètres KEY:VALUE supplémentaires avec --resume ; le fichier de workflow sauvegardé, les paramètres et les sorties persistées sont réutilisés.

Emplacement et format du fichier

• Chemin par défaut : .asc/workflow.json
• Chemin surchargé : asc workflow run --file ./chemin/vers/workflow.json <nom>
• Les commentaires JSONC sont pris en charge.
• Hooks de premier niveau : before_all, after_all, error
• Clés d'un workflow : description, private, env, steps
• Formes d'étape :
  • chaîne courte : "echo hello"
  • commande shell run
  • appel de sous-workflow workflow
  • étiquette name
  • nom de variable conditionnelle if
  • surcharges d'environnement with pour les étapes d'appel de workflow
  • mappage outputs pour l'extraction JSON de stdout à partir d'étapes nommées
  • politique de nouvelle tentative retry à délai fixe pour une étape run
  • durée timeout positive par tentative pour une étape run

Sorties

Les étapes d'exécution peuvent déclarer des sorties. La commande doit émettre du JSON sur stdout, donc passez --output json pour les commandes asc qui produisent des sorties.

Les références de sortie utilisent :

${steps.nom_etape.NOM_SORTIE}

Règles :

• Une étape qui déclare des outputs doit avoir un name sûr pour les références.
• Les sorties sont autorisées sur les étapes run, pas sur les étapes d'appel de workflow.
• Les noms produisant des sorties doivent être uniques parmi les workflows pouvant s'exécuter ensemble dans le même graphe d'exécution.
• Les sorties persistées sont stockées dans l'état de l'exécution du workflow, donc ne mappez pas de secrets dans les sorties.

Tentatives limitées et timeout

N'ajoutez une tentative qu'aux commandes dont vous avez déterminé qu'elles sont sûres à répéter. L'exécuteur ne classe pas les commandes ni ne réessaie les mutations tout seul.

{
  "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 compte la première tentative et doit être compris entre 2 et 100. Les délais de tentative et les timeouts doivent être des durées positives ne dépassant pas 24 heures. Les deux champs fonctionnent uniquement sur les étapes run, pas sur les appels de workflow ni les hooks de cycle de vie.

Un timeout sans tentative est terminal car la commande peut s'être terminée à distance. Associer tentative et timeout est le signal explicite qu'une autre tentative est sûre. La reprise nécessite soit un point de contrôle réussi, soit une étape échouée avec tentatives activées ; les échecs d'extraction de sortie ne peuvent pas être repris.

Paramètres d'exécution

asc workflow run <nom> [KEY:VALUE ...] prend en charge les deux séparateurs :

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

Les clés répétées sont remportées par la dernière écriture. Dans les commandes shell, référencez les paramètres via l'expansion shell comme $VERSION.

Priorité des variables d'environnement

Exécution du workflow principal :

definition.env < workflow.env < paramètres CLI

Appel de sous-workflow avec with :

env du sous-workflow < env et paramètres de l'appelant < step with

Conditions

Ajoutez "if": "NOM_VAR" à une étape. Les valeurs vraies sont 1, true, yes, y et on, insensibles à la casse. La recherche vérifie d'abord les env/paramètres fusionnés du workflow, puis l'environnement du processus.

Exemple de 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": "Résoudre la dernière build et la distribuer à 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": "Valider, stagifier et soumettre une version de l'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": "Upload de haut niveau plus soumission pour review App Store",
      "steps": [
        {
          "name": "publish",
          "run": "asc publish appstore --app $APP_ID --ipa ./build/MyApp.ipa --version $VERSION --wait --submit --confirm --output json"
        }
      ]
    }
  }
}

Invocations utiles

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"

Règles de sécurité

• Traitez .asc/workflow.json comme du code ; exécutez uniquement des fichiers de workflow de confiance.
• Évitez d'exécuter des workflows provenant de PR non fiables avec des secrets.
• Conservez les fichiers de workflow dans le contrôle de version.
• Validez d'abord, simulez ensuite, puis exécutez.
• Utilisez des ID explicites et --confirm pour les étapes de mutation.
• Utilisez asc validate, asc release stage, asc review submit et asc publish appstore ; n'utilisez pas les commandes de soumission supprimées.