rorkai/app-store-connect-cli-skills

flujo de trabajo asc

Usa esta habilidad cuando necesites automatización tipo lane dentro de la CLI usando:

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

Los flujos de trabajo son archivos de automatización locales al repositorio. Ejecutan comandos shell de confianza, transmiten la salida de los pasos a stderr y mantienen stdout como JSON legible por máquina.

Descubrimiento de comandos

Verifica siempre las banderas con:

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

Flujo completo

1. Crea .asc/workflow.json.
2. Valida la estructura y las referencias:

asc workflow validate

3. Descubre flujos públicos:

asc workflow list
asc workflow list --all

4. Vista previa de la ejecución:

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

5. Ejecuta:

asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

6. Si una ejecución recuperable falla, reanuda con el ID de ejecución del resultado JSON:

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

No pases parámetros KEY:VALUE extras con --resume; el archivo de flujo guardado, los parámetros y las salidas guardadas se reutilizan.

Ubicación y formato del archivo

• Ruta predeterminada: .asc/workflow.json
• Ruta alternativa: asc workflow run --file ./path/to/workflow.json <nombre>
• Se admiten comentarios JSONC.
• Hooks de nivel superior: before_all, after_all, error
• Claves de flujo: description, private, env, steps
• Formas de los pasos:
  • cadena corta: "echo hello"
  • run comando shell
  • workflow llamada a subflujo
  • name etiqueta
  • if nombre de variable condicional
  • with anulaciones de entorno para pasos de llamada a flujo
  • outputs mapa para extraer JSON stdout de pasos de ejecución nombrados
  • retry política de reintento con retraso fijo para un paso run
  • timeout duración positiva por intento para un paso run

Salidas

Los pasos de ejecución pueden declarar salidas. El comando debe emitir JSON en stdout, así que pasa --output json para los comandos asc que producen salidas.

Las referencias a salidas usan:

${steps.nombre_del_paso.NOMBRE_DE_SALIDA}

Reglas:

• Un paso que declara outputs debe tener un name seguro para referencias.
• Las salidas están permitidas en pasos run, no en pasos de llamada a flujo.
• Los nombres que producen salidas deben ser únicos entre los flujos que pueden ejecutarse juntos en el mismo grafo de ejecución.
• Las salidas guardadas se almacenan en el estado de ejecución del flujo, por lo que no mapees secretos en las salidas.

Reintento acotado y tiempo de espera

Agrega reintento solo a comandos que hayas determinado que son seguros de repetir. El ejecutor no clasifica comandos ni reintenta mutaciones por sí mismo.

{
  "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 cuenta el primer intento y debe estar entre 2 y 100. Los retrasos de reintento y los tiempos de espera deben ser duraciones positivas no mayores a 24 horas. Ambos campos funcionan solo en pasos run, no en llamadas a flujo o hooks de ciclo de vida.

Un tiempo de espera sin reintento es terminal porque el comando puede haberse completado de forma remota. Emparejar reintento y tiempo de espera es la señal explícita de que otro intento es seguro. Reanudar requiere un punto de control exitoso o un paso fallido con reintento habilitado; las fallas de extracción de salidas no se pueden reanudar.

Parámetros de tiempo de ejecución

asc workflow run <nombre> [CLAVE:VALOR ...] admite ambos separadores:

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

Las claves repetidas se resuelven con última escritura. En comandos shell, referencia los parámetros mediante expansión shell como $VERSION.

Precedencia de entorno

Ejecución principal del flujo:

definition.env < workflow.env < CLI params

Llamada a subflujo con with:

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

Condicionales

Agrega "if": "NOMBRE_VAR" a un paso. Los valores verdaderos son 1, true, yes, y y on, sin distinción de mayúsculas/minúsculas. La búsqueda verifica primero el entorno/parámetros combinados del flujo, luego el entorno del proceso.

Ejemplo de flujo

{
  "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": "Resuelve el último build y distribúyelo a 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": "Valida, prepara y envía una versión de 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": "Carga de alto nivel más envío a revisión de App Store",
      "steps": [
        {
          "name": "publish",
          "run": "asc publish appstore --app $APP_ID --ipa ./build/MyApp.ipa --version $VERSION --wait --submit --confirm --output json"
        }
      ]
    }
  }
}

Invocaciones útiles

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"

Reglas de seguridad

• Trata .asc/workflow.json como código; solo ejecuta archivos de flujo confiables.
• Evita ejecutar flujos de PRs no confiables con secretos.
• Mantén los archivos de flujo en control de versiones.
• Primero valida, luego haz una vista previa, después ejecuta.
• Usa IDs explícitos y --confirm para pasos mutantes.
• Usa asc validate, asc release stage, asc review submit y asc publish appstore; no uses comandos de envío eliminados.