Builds de Preview em PRs

Q: Como designers obtêm preview iOS sem UDIDs?

Use o perfil preview-simulator - baixe o build do simulador; o designer executa no simulador do Xcode.

Q: O preview deve usar uma API diferente?

Defina env.API_URL no perfil de preview para o ambiente de staging - nunca aponte builds de preview para APIs de escrita de produção.

Um guia para distribuição via QR code de builds de preview do EAS em pull requests - para que design e QA possam revisar em dispositivos reais antes do merge.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// eas.json - perfil de preview
{
  "build": {
    "preview": {
      "distribution": "internal",
      "channel": "preview",
      "android": { "buildType": "apk" },
      "ios": { "simulator": false }
    }
  }
}

# .github/workflows/preview-pr.yml
name: Preview Build
on:
  pull_request:
    types: [labeled]
 
jobs:
  preview:
    if: contains(github.event.pull_request.labels.*.name, 'needs-preview')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}
      - run: npm ci
      - id: build
        run: |
          eas build --profile preview --platform android --non-interactive --json > build.json
          echo "url=$(jq -r '.[0].artifacts.buildUrl' build.json)" >> $GITHUB_OUTPUT
      - uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 📱 Preview build\n\nInstall: ${{ steps.build.outputs.url }}\n\nScan QR on device or open link.`
            })

Quando usar isso:

Fluxos de navegação nativa, gestos ou câmera que designers precisam ver em hardware.
Aprovação de QA antes do merge em funcionalidades que o Jest não consegue cobrir.
Revisão de UI multiplataforma quando o Storybook web não é suficiente.
Demos para stakeholders sem esperar pelos builds noturnos ou de release.

Exemplo de Trabalho

Estrutura do projeto:

your-expo-app/
  .github/workflows/preview-pr.yml
  .eas/workflows/preview-pr.yml   # alternativa opcional nativa do EAS
  eas.json
  app.json

Perfis do eas.json

{
  "build": {
    "preview": {
      "distribution": "internal",
      "channel": "preview",
      "env": {
        "APP_VARIANT": "preview"
      },
      "android": {
        "buildType": "apk"
      },
      "ios": {
        "simulator": false
      }
    },
    "preview-simulator": {
      "distribution": "internal",
      "ios": { "simulator": true },
      "android": { "buildType": "apk" }
    }
  }
}

// app.config.ts - banner de variante opcional
const IS_PREVIEW = process.env.APP_VARIANT === "preview";
 
export default {
  expo: {
    name: IS_PREVIEW ? "MyApp (Preview)" : "MyApp",
    // ...
  },
};

GitHub Actions - comentar com link de instalação

name: Preview on PR
on:
  pull_request:
    types: [opened, synchronize, labeled]
 
concurrency:
  group: preview-${{ github.event.pull_request.number }}
  cancel-in-progress: true
 
jobs:
  preview:
    if: contains(github.event.pull_request.labels.*.name, 'needs-preview')
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}
      - run: npm ci
      - run: npm run typecheck
      - name: EAS preview build
        id: eas
        run: |
          eas build \
            --profile preview \
            --platform android \
            --non-interactive \
            --json > build-output.json
          BUILD_URL=$(jq -r '.[0].artifacts.buildUrl // .artifacts.buildUrl' build-output.json)
          QR_URL=$(jq -r '.[0].artifacts.applicationArchiveUrl // empty' build-output.json)
          echo "build_url=$BUILD_URL" >> $GITHUB_OUTPUT
      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            const url = '${{ steps.eas.outputs.build_url }}';
            const body = [
              '## 📱 Android preview build',
              '',
              `**Install:** ${url}`,
              '',
              '1. Open the link on your Android device',
              '2. Scan the QR code or download the APK',
              '3. Allow install from unknown sources if prompted (internal testing only)',
              '',
              '_Built from commit `${{ github.sha }}` with profile `preview`._'
            ].join('\n');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body
            });

Alternativa EAS Workflows

# .eas/workflows/preview-pr.yml
name: Preview PR
on:
  pull_request:
    types: [labeled]
 
jobs:
  quality:
    if: ${{ github.event.pull_request.labels.*.name contains 'needs-preview' }}
    steps:
      - uses: eas/checkout
      - uses: eas/install_node_modules
      - run: npm run typecheck
 
  build_preview:
    needs: [quality]
    type: build
    params:
      platform: android
      profile: preview

Execute manualmente ao testar:

npx eas-cli@latest workflow:run .eas/workflows/preview-pr.yml

O que isso demonstra:

distribution: internal - O EAS hospeda a página de instalação com QR code (Distribuição Interna).
buildType: apk no Android - instalação manual sem a trilha interna do Play.
Gatilho por rótulo - apenas PRs com needs-preview consomem créditos de build.
Comentário no PR - QA e design recebem o link sem precisar procurar no painel do EAS.
Concorrência - o último push cancela o preview anterior para o mesmo número de PR.

Mergulho Profundo

Quem Instala o Quê

Plataforma	Perfil de Preview	Instalador	Ideal para
Android	`apk` + internal	Link QR / APK	QA em dispositivos físicos
Dispositivo iOS	ad hoc / internal	QR via EAS	UDIDs registrados
iOS	`simulator: true`	Tar `.app`	Designer no simulador do Mac
Ambos	+ `channel: preview`	+ `eas update` opcional	Correção JS no mesmo binário de preview

Estratégias de Gatilho

# Controlado por rótulo (recomendado)
if: contains(github.event.pull_request.labels.*.name, 'needs-preview')
 
# Filtro de caminho - apenas alterações que impactam o nativo
on:
  pull_request:
    paths:
      - "app/**"
      - "src/**"
      - "app.config.ts"
      - "plugins/**"

Estratégia	Custo de Crédito	Risco
Cada push de PR	Alto	Melhor cobertura
Rótulo `needs-preview`	Baixo	Requer disciplina
Filtro de caminho	Médio	Perde alterações em pacotes compartilhados se o filtro for muito restrito

Documente em CONTRIBUTING.md:

## Builds de preview
Adicione o rótulo `needs-preview` quando QA ou design precisar de um build para dispositivo.
**Não** adicione para alterações apenas de cópia ou apenas de teste.

OTA no Canal de Preview

Após o binário de preview existir, correções em JS podem ser enviadas sem reconstruir:

eas update --channel preview --message "PR-${{ github.event.pull_request.number }}"

O binário de preview deve corresponder ao runtimeVersion - Política de Versão de Runtime
Comente no PR quando o OTA for enviado para que o QA atualize o bundle
Alterações nativas ainda exigem um novo build de preview

Combine com Maestro Smoke

Quando houver alterações de navegação, execute um fluxo leve do Maestro no build_id de preview antes do merge:

  maestro_smoke:
    needs: [build_preview]
    type: maestro
    params:
      build_id: ${{ needs.build_preview.outputs.build_id }}
      flow_path: [".maestro/smoke.yml"]

Falhe a verificação do PR se o smoke falhar - opcional, mas valioso para refatorações de roteamento
Mantenha o smoke com 3–5 passos - Maestro E2E

Armadilhas

Preview em cada commit - Esgotamento de créditos do EAS no meio do sprint. Solução: Gatilho por rótulo + cancelamento de concorrência.
Preview iOS sem dispositivos registrados - Build ad hoc não instala em lugar nenhum. Solução: Mantenha a lista de dispositivos no portal Apple Developer ou use o perfil de simulador para designers.
QA testa o Expo Go - Bundle ID e módulos nativos diferem do build de preview. Solução: Sempre distribua o link do artefato EAS.
Comentário de PR desatualizado - Link de instalação antigo após rebase. Solução: Edite o comentário ou poste um novo comentário por build; inclua github.sha no corpo.
Credenciais de produção no perfil de preview - Assinatura acidental na loja no branch de feature. Solução: Perfil preview separado sem chaves de produção autoIncrement.
Permissão pull-requests: write ausente - O passo de comentário falha silenciosamente ou gera erro. Solução: Adicione o bloco permissions no workflow.

Alternativas

Alternativa	Use Quando	Não Use Quando
Distribuição interna EAS QR	Padrão para QA em dispositivo	Você precisa de rollout faseado na trilha interna do Play
`eas update` no canal de preview	Ajustes de PR apenas em JS	Novo módulo nativo adicionado
TestFlight externo + número do PR	Equipe com foco em iOS já usa ASC	Feedback rápido de APK Android necessário
Apenas testes de screenshot	Layout/cópia pura	Gestos, câmera, haptics

FAQs

Como o QA instala no Android?

Abra o link da página de build do EAS do comentário do PR → escaneie o QR code → instale o APK. Habilite "instalar apps desconhecidos" para o navegador, se solicitado.

Posso construir iOS e Android em um único job de PR?

eas build --profile preview --platform all --non-interactive

Custa dois builds; comente ambos os links ou construa apenas Android para feedback mais rápido.

Como designers obtêm preview iOS sem UDIDs?

Use o perfil preview-simulator - baixe o build do simulador; o designer executa no simulador do Xcode.

O preview deve usar uma API diferente?

Defina env.API_URL no perfil de preview para o ambiente de staging - nunca aponte builds de preview para APIs de escrita de produção.

Relacionados

GitHub Actions + EAS - segredos e expo-github-action
EAS Workflows - itens de checklist do tier de preview
Distribuição Interna - trilhas ad hoc e enterprise
Perfis de Build e Flavors - preview vs produção
Noções Básicas de Teste Mobile - o que os previews complementam
Maestro E2E - smoke no build_id de preview
Noções Básicas de CI/CD Mobile - verificações de PR vs builds de preview

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).

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// eas.json - perfil de preview
{
  "build": {
    "preview": {
      "distribution": "internal",
      "channel": "preview",
      "android": { "buildType": "apk" },
      "ios": { "simulator": false }
    }
  }
}

# .github/workflows/preview-pr.yml
name: Preview Build
on:
  pull_request:
    types: [labeled]
 
jobs:
  preview:
    if: contains(github.event.pull_request.labels.*.name, 'needs-preview')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}
      - run: npm ci
      - id: build
        run: |
          eas build --profile preview --platform android --non-interactive --json > build.json
          echo "url=$(jq -r '.[0].artifacts.buildUrl' build.json)" >> $GITHUB_OUTPUT
      - uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 📱 Preview build\n\nInstall: ${{ steps.build.outputs.url }}\n\nScan QR on device or open link.`
            })

Quando usar isso:

Fluxos de navegação nativa, gestos ou câmera que designers precisam ver em hardware.
Aprovação de QA antes do merge em funcionalidades que o Jest não consegue cobrir.
Revisão de UI multiplataforma quando o Storybook web não é suficiente.
Demos para stakeholders sem esperar pelos builds noturnos ou de release.

Exemplo de Trabalho

Estrutura do projeto:

your-expo-app/
  .github/workflows/preview-pr.yml
  .eas/workflows/preview-pr.yml   # alternativa opcional nativa do EAS
  eas.json
  app.json

Perfis do eas.json

{
  "build": {
    "preview": {
      "distribution": "internal",
      "channel": "preview",
      "env": {
        "APP_VARIANT": "preview"
      },
      "android": {
        "buildType": "apk"
      },
      "ios": {
        "simulator": false
      }
    },
    "preview-simulator": {
      "distribution": "internal",
      "ios": { "simulator": true },
      "android": { "buildType": "apk" }
    }
  }
}

// app.config.ts - banner de variante opcional
const IS_PREVIEW = process.env.APP_VARIANT === "preview";
 
export default {
  expo: {
    name: IS_PREVIEW ? "MyApp (Preview)" : "MyApp",
    // ...
  },
};

GitHub Actions - comentar com link de instalação

name: Preview on PR
on:
  pull_request:
    types: [opened, synchronize, labeled]
 
concurrency:
  group: preview-${{ github.event.pull_request.number }}
  cancel-in-progress: true
 
jobs:
  preview:
    if: contains(github.event.pull_request.labels.*.name, 'needs-preview')
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - uses: expo/expo-github-action@v8
        with:
          eas-version: latest
          token: ${{ secrets.EXPO_TOKEN }}
      - run: npm ci
      - run: npm run typecheck
      - name: EAS preview build
        id: eas
        run: |
          eas build \
            --profile preview \
            --platform android \
            --non-interactive \
            --json > build-output.json
          BUILD_URL=$(jq -r '.[0].artifacts.buildUrl // .artifacts.buildUrl' build-output.json)
          QR_URL=$(jq -r '.[0].artifacts.applicationArchiveUrl // empty' build-output.json)
          echo "build_url=$BUILD_URL" >> $GITHUB_OUTPUT
      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            const url = '${{ steps.eas.outputs.build_url }}';
            const body = [
              '## 📱 Android preview build',
              '',
              `**Install:** ${url}`,
              '',
              '1. Open the link on your Android device',
              '2. Scan the QR code or download the APK',
              '3. Allow install from unknown sources if prompted (internal testing only)',
              '',
              '_Built from commit `${{ github.sha }}` with profile `preview`._'
            ].join('\n');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body
            });

Alternativa EAS Workflows

# .eas/workflows/preview-pr.yml
name: Preview PR
on:
  pull_request:
    types: [labeled]
 
jobs:
  quality:
    if: ${{ github.event.pull_request.labels.*.name contains 'needs-preview' }}
    steps:
      - uses: eas/checkout
      - uses: eas/install_node_modules
      - run: npm run typecheck
 
  build_preview:
    needs: [quality]
    type: build
    params:
      platform: android
      profile: preview

Execute manualmente ao testar:

npx eas-cli@latest workflow:run .eas/workflows/preview-pr.yml

O que isso demonstra:

distribution: internal - O EAS hospeda a página de instalação com QR code (Distribuição Interna).
buildType: apk no Android - instalação manual sem a trilha interna do Play.
Gatilho por rótulo - apenas PRs com needs-preview consomem créditos de build.
Comentário no PR - QA e design recebem o link sem precisar procurar no painel do EAS.
Concorrência - o último push cancela o preview anterior para o mesmo número de PR.

Mergulho Profundo

Quem Instala o Quê

Plataforma	Perfil de Preview	Instalador	Ideal para
Android	`apk` + internal	Link QR / APK	QA em dispositivos físicos
Dispositivo iOS	ad hoc / internal	QR via EAS	UDIDs registrados
iOS	`simulator: true`	Tar `.app`	Designer no simulador do Mac
Ambos	+ `channel: preview`	+ `eas update` opcional	Correção JS no mesmo binário de preview

Estratégias de Gatilho

# Controlado por rótulo (recomendado)
if: contains(github.event.pull_request.labels.*.name, 'needs-preview')
 
# Filtro de caminho - apenas alterações que impactam o nativo
on:
  pull_request:
    paths:
      - "app/**"
      - "src/**"
      - "app.config.ts"
      - "plugins/**"

Estratégia	Custo de Crédito	Risco
Cada push de PR	Alto	Melhor cobertura
Rótulo `needs-preview`	Baixo	Requer disciplina
Filtro de caminho	Médio	Perde alterações em pacotes compartilhados se o filtro for muito restrito

Documente em CONTRIBUTING.md:

## Builds de preview
Adicione o rótulo `needs-preview` quando QA ou design precisar de um build para dispositivo.
**Não** adicione para alterações apenas de cópia ou apenas de teste.

OTA no Canal de Preview

Após o binário de preview existir, correções em JS podem ser enviadas sem reconstruir:

eas update --channel preview --message "PR-${{ github.event.pull_request.number }}"

O binário de preview deve corresponder ao runtimeVersion - Política de Versão de Runtime
Comente no PR quando o OTA for enviado para que o QA atualize o bundle
Alterações nativas ainda exigem um novo build de preview

Combine com Maestro Smoke

Quando houver alterações de navegação, execute um fluxo leve do Maestro no build_id de preview antes do merge:

  maestro_smoke:
    needs: [build_preview]
    type: maestro
    params:
      build_id: ${{ needs.build_preview.outputs.build_id }}
      flow_path: [".maestro/smoke.yml"]

Falhe a verificação do PR se o smoke falhar - opcional, mas valioso para refatorações de roteamento
Mantenha o smoke com 3–5 passos - Maestro E2E

Armadilhas

Preview em cada commit - Esgotamento de créditos do EAS no meio do sprint. Solução: Gatilho por rótulo + cancelamento de concorrência.
Preview iOS sem dispositivos registrados - Build ad hoc não instala em lugar nenhum. Solução: Mantenha a lista de dispositivos no portal Apple Developer ou use o perfil de simulador para designers.
QA testa o Expo Go - Bundle ID e módulos nativos diferem do build de preview. Solução: Sempre distribua o link do artefato EAS.
Comentário de PR desatualizado - Link de instalação antigo após rebase. Solução: Edite o comentário ou poste um novo comentário por build; inclua github.sha no corpo.
Credenciais de produção no perfil de preview - Assinatura acidental na loja no branch de feature. Solução: Perfil preview separado sem chaves de produção autoIncrement.
Permissão pull-requests: write ausente - O passo de comentário falha silenciosamente ou gera erro. Solução: Adicione o bloco permissions no workflow.

Alternativas

Alternativa	Use Quando	Não Use Quando
Distribuição interna EAS QR	Padrão para QA em dispositivo	Você precisa de rollout faseado na trilha interna do Play
`eas update` no canal de preview	Ajustes de PR apenas em JS	Novo módulo nativo adicionado
TestFlight externo + número do PR	Equipe com foco em iOS já usa ASC	Feedback rápido de APK Android necessário
Apenas testes de screenshot	Layout/cópia pura	Gestos, câmera, haptics

FAQs

Como o QA instala no Android?

Abra o link da página de build do EAS do comentário do PR → escaneie o QR code → instale o APK. Habilite "instalar apps desconhecidos" para o navegador, se solicitado.

Posso construir iOS e Android em um único job de PR?

eas build --profile preview --platform all --non-interactive

Custa dois builds; comente ambos os links ou construa apenas Android para feedback mais rápido.

Como designers obtêm preview iOS sem UDIDs?

Use o perfil preview-simulator - baixe o build do simulador; o designer executa no simulador do Xcode.

O preview deve usar uma API diferente?

Defina env.API_URL no perfil de preview para o ambiente de staging - nunca aponte builds de preview para APIs de escrita de produção.

Relacionados

GitHub Actions + EAS - segredos e expo-github-action
EAS Workflows - itens de checklist do tier de preview
Distribuição Interna - trilhas ad hoc e enterprise
Perfis de Build e Flavors - preview vs produção
Noções Básicas de Teste Mobile - o que os previews complementam
Maestro E2E - smoke no build_id de preview
Noções Básicas de CI/CD Mobile - verificações de PR vs builds de preview

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).

Builds de Preview em PRs

Buscar na documentação

Builds de Preview em PRs