Workflows do EAS

Um checklist para pipelines YAML que constroem, testam, enviam e atualizam aplicativos Expo SDK 57 na infraestrutura do EAS. Percorra cada item antes de considerar seu trem de lançamento pronto para produção.

Como Usar Este Checklist

• Execute os Níveis 1–2 antes do seu primeiro workflow:run; Níveis 3–5 antes que a automação da loja entre em vigor.
• Mantenha um workflow por intenção - pr-quality.yml, preview-pr.yml, store-release.yml - não um mega-arquivo.
• Espelhe os scripts npm dos Portões de Qualidade de CI - desenvolvedores e workflows chamam os mesmos comandos.
• Reexecute níveis falhados após correções; um eas build local verde não significa que o YAML do workflow está configurado corretamente.

Visão Geral dos Níveis

Nível 1: Configuração do Projeto (1–6)

1. Projeto EAS vinculado - app.json / app.config.ts contém extra.eas.projectId após eas init.

   • Sinal: eas workflow:run solicita a criação interativa de um projeto.
   • Correção: npx eas-cli@latest init no SDK 57; comite o ID do projeto gerado.
   • Prioridade: P0 - bloqueia todas as execuções de workflow.

2. Perfis eas.json existem para cada intenção - no mínimo preview, production e e2e-test.

   • Sinal: params.profile do workflow referencia uma chave ausente.
   • Correção: Perfis e Flavors de Build.
   • Prioridade: P0.

3. Diretório .eas/workflows/ comitado - YAML é código fonte, revisado como alterações de aplicação.

   • Sinal: Workflows existem apenas no laptop de um engenheiro.
   • Correção: Adicione quality-gates.yml primeiro; expanda a partir daí.
   • Prioridade: P0.

4. Conta de robô EXPO_TOKEN em segredos do CI - não um token de acesso pessoal vinculado a um único desenvolvedor.

   • Sinal: Workflows falham quando esse desenvolvedor está de férias.
   • Correção: Dashboard Expo → Access Tokens → usuário de máquina; armazene em segredos do GitHub / EAS.
   • Prioridade: P0.

5. CLI do Workflow testado localmente - npx eas-cli@latest workflow:run .eas/workflows/quality-gates.yml.

   • Sinal: Primeira execução falha na sintaxe YAML descoberta apenas na nuvem.
   • Correção: Execute manualmente antes de configurar on: pull_request.
   • Prioridade: P1.

6. Grupo de concorrência configurado - cancela execuções substituídas em pushes rápidos de PR.

   • Sinal: Cinco builds idênticos ficam na fila para um PR.
   • Correção:

concurrency:
  cancel_in_progress: true
  group: ${{ workflow.filename }}-${{ github.ref }}

• Prioridade: P1.

Nível 2: Workflows de Qualidade e PR (7–12)

7. Job de qualidade customizado antes de qualquer type: build - lint, typecheck, teste em eas/checkout.
   • Sinal: Builds nativos começam enquanto o TypeScript está quebrado.
   • Correção:

# .eas/workflows/quality-gates.yml
name: Quality Gates
on:
  pull_request:
    branches: [main]
 
jobs:
  quality:
    steps:
      - uses: eas/checkout
      - uses: eas/use_npm_token
      - uses: eas/install_node_modules
      - run: npx expo customize tsconfig.json
      - run: npm run format:check
      - run: npm run lint
      - run: npm run typecheck
      - run: npm run test -- --ci

• Prioridade: P0 em todo PR.

8. needs: [quality] em jobs de build downstream - builds esperam pelos scripts verdes.

   • Sinal: build_ios e quality rodam em paralelo.
   • Correção: Adicione o array needs em cada job type: build.
   • Prioridade: P0.

9. Trigger de PR corresponde à política de branch - pull_request.branches: [main] ou release/*.

   • Sinal: Workflows nunca disparam em forks da equipe ou na branch base errada.
   • Correção: Alinhe com os alvos de proteção de branch do GitHub.
   • Prioridade: P1.

10. Perfil de build de preview para workflows de PR - distribution: internal ou simulator / apk conforme necessário.

    • Sinal: Workflow de PR tenta credenciais de production.
    • Correção: Perfil preview separado em eas.json - Distribuição Interna.
    • Prioridade: P0 para previews de PR.

11. Job de build produz build_id consumido downstream - Maestro e submit referenciam o mesmo artefato.

    • Sinal: Job de submit chama --latest em vez de ID fixado.
    • Correção:

  build_android:
    needs: [quality]
    type: build
    params:
      platform: android
      profile: preview
 
  maestro_smoke:
    needs: [build_android]
    type: maestro
    params:
      build_id: ${{ needs.build_android.outputs.build_id }}
      flow_path: [".maestro/smoke.yml"]

- **Prioridade:** P0 antes do submit automatizado.

12. appId do Maestro corresponde aos IDs de bundle do eas.json - fluxos iniciam o app construído, não o Expo Go. - Sinal: Job do Maestro é bem-sucedido localmente, mas falha no workflow - appId incorreto. - Correção: Maestro E2E. - Prioridade: P0 no primeiro workflow de E2E.

Nível 3: Build, Submit & Release (13–18)

13. Workflow de build de produção acionado por tag semver - on.push.tags: ["v*"].

    • Sinal: Cada merge para main envia para as lojas.
    • Correção: Lançamento guiado por tag; workflow_dispatch manual para hotfixes.
    • Prioridade: P0.

14. type: build com profile: production e autoIncrement - números de build avançam sem edição manual de plists.

    • Sinal: Loja rejeita versionCode / número de build duplicado.
    • Correção: "autoIncrement": true no perfil de produção do eas.json.
    • Prioridade: P0.

15. type: submit referencia build_id do job de build pareado - não --latest.

    • Sinal: Loja recebe um build que o QA nunca testou.
    • Correção:

  submit_ios:
    needs: [smoke_ios]
    type: submit
    params:
      platform: ios
      build_id: ${{ needs.build_ios.outputs.build_id }}

- **Prioridade:** P0 - [Promoção Automatizada para a Loja](./automated-store-promotion.md).

16. Smoke tests do Maestro controlam o submit - pelo menos login + um caminho crítico de receita. - Sinal: Submit roda imediatamente após o build sem verificação em dispositivo. - Correção: needs: [maestro_smoke] nos jobs de submit. - Prioridade: P0 para promoção automatizada.

17. Jobs de submit iOS e Android em paralelo após smoke específico da plataforma - não serializar desnecessariamente.

    • Sinal: Android espera pelo processamento do TestFlight do iOS.
    • Correção: Cadeias separadas de build → smoke → submit por plataforma.
    • Prioridade: P1.

18. Notificação Slack / email sobre falha do workflow - a equipe de plantão sabe antes dos usuários.

    • Sinal: Lançamento falho descoberto na segunda-feira de manhã.
    • Correção: Notificações do GitHub ou passo customizado postando em webhook.
    • Prioridade: P1.

Nível 4: Workflows de Atualização OTA (19–24)

19. Job type: update visa canal explícito - production, staging, não o padrão implícito.

    • Sinal: Bundle de staging promovido para o canal de produção por erro de digitação.
    • Correção: Canais e Branches de Lançamento.
    • Prioridade: P0.

20. Workflow de OTA executa portões de qualidade primeiro - mesmo lint/tsc/test dos checks de PR.

    • Sinal: TypeScript quebrado enviado via OTA.
    • Correção: needs: [quality] antes de type: update.
    • Prioridade: P0.

21. Política de runtimeVersion documentada - OTA compatível apenas com binários da loja correspondentes.

    • Sinal: OTA falha em versões mais antigas do app.
    • Correção: Política de Versão de Runtime.
    • Prioridade: P0.

22. Mensagem OTA inclui SHA do Git - rastreabilidade no dashboard do EAS.

    • Sinal: Não é possível correlacionar atualização com PR mesclado.
    • Correção: message: ${{ github.sha }} nos parâmetros de update.
    • Prioridade: P1.

23. Workflow de Rollback documentado e testado - eas update --roll-back ou republicação de canal.

    • Sinal: Primeiro incidente de produção não tem runbook.
    • Correção: Runbook de Rollback.
    • Prioridade: P0 antes da primeira OTA para produção.

24. Alterações que impactam o nativo bloqueadas de workflow apenas de OTA - edições de plugin de configuração disparam workflow de build.

    • Sinal: OTA importa expo-camera não presente no binário instalado.
    • Correção: Filtros de caminho ou rótulo de revisão exigido native-change.
    • Prioridade: P0.

Nível 5: Operações e Custo (25–30)

25. Tokens de skip documentados - [eas skip] na mensagem de commit para pushes apenas de documentação.

    • Sinal: Equipe evita workflows completamente porque não pode pular.
    • Correção: Documente em CONTRIBUTING.md; não use em excesso.
    • Prioridade: P2.

26. Builds de preview de PR com filtro por rótulo ou caminho - não cada erro de digitação aciona build do EAS.

    • Sinal: Queima de crédito do EAS excede o orçamento no meio do trimestre.
    • Correção: Builds de Preview em PRs.
    • Prioridade: P1.

27. Matriz de perfis de build documentada - qual perfil roda em PR, noturno, release.

    • Sinal: Novo engenheiro dispara build de produção a partir de branch de feature.
    • Correção: Tabela no README ou Noções Básicas de CI/CD Mobile.
    • Prioridade: P1.

28. Segredos rotacionados em agendamento - EXPO_TOKEN, chave da App Store Connect API, conta de serviço do Play.

    • Sinal: Vazamento de token exige revogação de emergência sem backup.
    • Correção: Entrada de calendário de rotação trimestral.
    • Prioridade: P1.

29. Duração do workflow monitorada - qualidade + build + Maestro p95 rastreados.

    • Sinal: Trem de lançamento perde a janela de sexta-feira silenciosamente.
    • Correção: Tempos de build do dashboard EAS; otimize o cache de install_node_modules.
    • Prioridade: P2.

30. Simulação de desastre: Maestro falho bloqueia submit - verificado em staging, não assumido.

    • Sinal: Job de submit tem fiação needs solta; falha de smoke ignorada.
    • Correção: Falhe intencionalmente um fluxo no workflow de staging trimestralmente.
    • Prioridade: P1.

Referência: Tipos de Job

Esboço Completo do Workflow de Lançamento

# .eas/workflows/store-release.yml
name: Store Release
on:
  push:
    tags: ["v*"]
 
jobs:
  quality:
    steps:
      - uses: eas/checkout
      - uses: eas/install_node_modules
      - run: npm run lint && npm run typecheck && npm run test -- --ci
 
  build_android:
    needs: [quality]
    type: build
    params: { platform: android, profile: production }
 
  smoke_android:
    needs: [build_android]
    type: maestro
    params:
      build_id: ${{ needs.build_android.outputs.build_id }}
      flow_path: [".maestro/smoke.yml"]
 
  submit_android:
    needs: [smoke_android]
    type: submit
    params:
      platform: android
      build_id: ${{ needs.build_android.outputs.build_id }}
 
  update_production:
    needs: [submit_android]
    type: update
    params:
      channel: production
      message: "Post-release OTA sync ${{ github.sha }}"

FAQs

npx eas-cli@latest workflow:run .eas/workflows/quality-gates.yml

Relacionados

• Noções Básicas de CI/CD Mobile - lanes de PR vs release vs noturnos
• GitHub Actions + EAS - configuração híbrida de CI
• Promoção Automatizada para a Loja - submit com portões após smoke
• Noções Básicas do EAS Build - perfis e primeiro build
• Noções Básicas de OTA Updates - restrições de OTA
• Maestro E2E - arquivos de fluxo e perfil e2e-test
• Portões de Qualidade de CI - scripts que os workflows devem chamar

Versões da Stack: Esta página foi escrita para React 19.2.3, React Native 0.86.0 e Expo SDK 57 (expo ~57.0.4).