rorkai/app-store-connect-cli-skills

workflow asc

Use este skill quando precisar de automação estilo lane dentro do CLI usando:

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

Workflows são arquivos de automação locais ao repositório. Eles executam comandos shell confiáveis, transmitem a saída das etapas para stderr e mantêm stdout como JSON legível por máquina.

Descoberta de comandos

Sempre verifique os sinalizadores com:

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

Fluxo completo

1. Crie .asc/workflow.json.
2. Valide a estrutura e as referências:

asc workflow validate

3. Descubra workflows públicos:

asc workflow list
asc workflow list --all

4. Visualize a execução:

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

5. Execute:

asc workflow run beta BUILD_ID:123456789 GROUP_ID:abcdef

6. Se uma execução recuperável falhar, retome com o ID da execução do resultado JSON:

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

Não passe parâmetros extras KEY:VALUE com --resume; o arquivo de workflow salvo, os parâmetros e as saídas persistidas são reutilizados.

Localização e formato do arquivo

• Caminho padrão: .asc/workflow.json
• Caminho alternativo: asc workflow run --file ./path/to/workflow.json <nome>
• Comentários JSONC são suportados.
• Hooks de nível superior: before_all, after_all, error
• Chaves do workflow: description, private, env, steps
• Formas de etapa:
  • atalho de string: "echo hello"
  • comando shell run
  • chamada de sub-workflow workflow
  • rótulo name
  • nome de variável condicional if
  • substituições de env para etapas de chamada de workflow with
  • mapa outputs para extração de JSON stdout de etapas de execução nomeadas
  • política de repetição com atraso fixo retry para uma etapa run
  • duração positiva por tentativa timeout para uma etapa run

Saídas

Etapas de execução podem declarar saídas. O comando deve emitir JSON no stdout, então passe --output json para comandos asc que produzem saídas.

Referências de saída usam:

${steps.nome_da_etapa.NOME_DA_SAIDA}

Regras:

• Uma etapa que declara outputs deve ter um name seguro para referência.
• Saídas são permitidas em etapas run, não em etapas de chamada de workflow.
• Nomes produtores de saída devem ser únicos entre workflows que podem executar juntos no mesmo grafo de execução.
• Saídas persistidas são armazenadas no estado da execução do workflow, portanto não mapeie segredos para saídas.

Retry e timeout limitados

Adicione retry apenas a comandos que você determinou serem seguros para repetir. O executor não classifica comandos nem repete mutações por conta própria.

{
  "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 conta a primeira tentativa e deve estar entre 2 e 100. Atrasos de retry e timeouts devem ser durações positivas não superiores a 24 horas. Ambos os campos funcionam apenas em etapas run, não em chamadas de workflow ou hooks de ciclo de vida.

Um timeout sem retry é terminal porque o comando pode ter sido concluído remotamente. Combinar retry e timeout é o sinal explícito de que outra tentativa é segura. Resumir requer um checkpoint bem-sucedido ou uma etapa com falha habilitada para retry; falhas de extração de saída não podem ser retomadas.

Parâmetros em tempo de execução

asc workflow run <nome> [KEY:VALUE ...] suporta ambos os separadores:

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

Chaves repetidas: a última vence. Em comandos shell, referencie parâmetros por meio de expansão shell como $VERSION.

Precedência de env

Execução principal do workflow:

definition.env < workflow.env < parâmetros CLI

Chamada de sub-workflow com with:

env do sub-workflow < env e parâmetros do chamador < with da etapa

Condicionais

Adicione "if": "NOME_DA_VAR" a uma etapa. Valores verdadeiros são 1, true, yes, y e on, sem distinção entre maiúsculas e minúsculas. A consulta verifica primeiro o env/parâmetros mesclados do workflow e, em seguida, o ambiente do processo.

Exemplo 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": "Resolver o build mais recente e distribuí-lo para o 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": "Validar, preparar e enviar uma versão da 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 alto nível mais envio para revisão da App Store",
      "steps": [
        {
          "name": "publish",
          "run": "asc publish appstore --app $APP_ID --ipa ./build/MyApp.ipa --version $VERSION --wait --submit --confirm --output json"
        }
      ]
    }
  }
}

Invocações úteis

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"

Regras de segurança

• Trate .asc/workflow.json como código; execute apenas arquivos de workflow confiáveis.
• Evite executar workflows de PRs não confiáveis com segredos.
• Mantenha os arquivos de workflow no controle de versão.
• Valide primeiro, faça dry-run depois, então execute.
• Use IDs explícitos e --confirm para etapas de mutação.
• Use asc validate, asc release stage, asc review submit e asc publish appstore; não use comandos de submissão removidos.