Deploy Mobile - CLI (Fastlane)

Última atualização: 23 de outubro de 2025

Visão Geral

Sistema automatizado de deploy para aplicações React Native utilizando Fastlane, permitindo a geração de builds Android (APK/AAB) e iOS (IPA) de forma eficiente e padronizada. A solução contempla múltiplos ambientes e métodos de distribuição, com scripts otimizados para CI/CD.

Plataformas Suportadas

Plataforma	Formatos	Métodos de Distribuição
Android	APK, AAB	Google Play Console, Distribuição Direta
iOS	IPA	TestFlight, App Store, Ad-Hoc

---

Pré-requisitos

Ferramentas Necessárias

Ferramenta	Versão Mínima	Finalidade
Node.js	18.x	Runtime JavaScript
Ruby	3.0+	Execução do Fastlane
Bundler	2.x	Gerenciamento de gems Ruby
Fastlane	2.228+	Automação de deploy
CocoaPods	1.15+	Gerenciamento de dependências iOS
Xcode	15.0+	Build iOS (somente macOS)
Android SDK	34+	Build Android

Instalação do Fastlane

# Instalar Bundler (se necessário)
gem install bundler

# Instalar dependências Ruby (incluindo Fastlane)
bundle install

# Verificar instalação
bundle exec fastlane --version

---

Estrutura de Arquivos

Arquivos de Configuração

Arquivo	Localização	Responsabilidade
Fastfile	fastlane/	Definição de lanes (comandos)
Appfile	fastlane/	Configurações do app iOS
Gemfile	Raiz	Dependências Ruby
.fastlaneignore	Raiz	Arquivos ignorados pelo Fastlane
setup-fastlane.sh	Raiz	Script de configuração inicial

Diretório Fastlane

fastlane/
├── Appfile           # Configurações de identidade iOS
├── Fastfile          # Definição de lanes
├── README.md         # Documentação gerada automaticamente
├── report.xml        # Relatório de execução
└── screenshots/      # Screenshots gerados (opcional)

---

Configuração Inicial

1. Configurar Appfile (iOS)

Edite o arquivo fastlane/Appfile com suas credenciais:

# fastlane/Appfile

app_identifier("com.suaempresa.seuapp")      # Bundle identifier do app
apple_id("seu.email@exemplo.com")            # Apple ID para login

# Team ID (encontre em: developer.apple.com/account)
team_id("XXXXXXXXXX")                        # Developer Team ID
itc_team_id("123456789")                     # App Store Connect Team ID

Como Encontrar Seus IDs

• Team ID: Acesse developer.apple.com/account → Membership
• App Store Connect Team ID: Acesse appstoreconnect.apple.com → Users and Access → Keys

2. Executar Setup Inicial

# Dar permissão de execução
chmod +x setup-fastlane.sh

# Executar script de setup
./setup-fastlane.sh

O script irá:

1. Instalar dependências Ruby
2. Verificar keystore Android
3. Instalar CocoaPods (iOS)
4. Validar instalação do Fastlane

---

Comandos de Deploy

Android

Gerar APK (Release)

# Via npm script (recomendado)
npm run deploy:android:apk

# Via Fastlane direto
bundle exec fastlane android apk

Saída: vidyaforce-release.apk na raiz do projeto

Gerar AAB (App Bundle)

# Via npm script (recomendado)
npm run deploy:android:aab

# Via Fastlane direto
bundle exec fastlane android aab

Saída: vidyaforce-release.aab na raiz do projeto

APK vs AAB

• APK: Distribuição direta, testes internos
• AAB: Formato obrigatório para Google Play Store (desde agosto/2021)

Gerar Ambos (APK + AAB)

# Gera tanto APK quanto AAB
npm run deploy:android

# Equivalente a:
bundle exec fastlane android build_all

---

iOS

Build para TestFlight

# Via npm script (recomendado)
npm run deploy:ios:testflight

# Via Fastlane direto
bundle exec fastlane ios deploy_testflight

O que acontece:

1. Incrementa automaticamente o build number
2. Instala/atualiza CocoaPods
3. Gera o arquivo IPA
4. Prepara para upload ao TestFlight

Saída: build/vidyaforce.ipa

Upload Manual

Após a geração do IPA, faça upload via Transporter app:

1. Abra o app Transporter (Mac App Store)
2. Arraste o arquivo build/vidyaforce.ipa
3. Clique em "Entregar"

Tela do App Store Connect mostrando builds entregues via Transporter

Build Somente (Sem Upload)

# Gera IPA sem enviar ao TestFlight
npm run deploy:ios:build

# Via Fastlane direto
bundle exec fastlane ios build

Build Ad-Hoc (Testes Externos)

# Para distribuição fora da App Store
npm run deploy:ios:adhoc

# Via Fastlane direto
bundle exec fastlane ios adhoc

Saída: build/vidyaforce-adhoc.ipa

Quando Usar Ad-Hoc

• Testes com dispositivos específicos (via UDID)
• Distribuição interna sem TestFlight
• Demonstrações para clientes

---

Deploy Completo (Android + iOS)

Gerar Todos os Builds

# Gera APK, AAB e IPA
npm run build:all

# Via Fastlane direto
bundle exec fastlane build_all

Arquivos Gerados:

• vidyaforce-release.apk
• vidyaforce-release.aab
• build/vidyaforce.ipa

Deploy Completo com TestFlight

# Gera builds Android e envia iOS para TestFlight
npm run deploy:all

# Via Fastlane direto
bundle exec fastlane deploy_all

---

Lanes Disponíveis

Fluxograma de Lanes

Lista Completa de Lanes

Android

Lane	Comando	Descrição
apk	fastlane android apk	Gera APK assinado
aab	fastlane android aab	Gera AAB assinado
build_all	fastlane android build_all	Gera APK + AAB
clean	fastlane android clean	Limpa build Android

iOS

Lane	Comando	Descrição
deploy_testflight	fastlane ios deploy_testflight	Build + Upload TestFlight
build	fastlane ios build	Gera IPA (App Store)
adhoc	fastlane ios adhoc	Gera IPA Ad-Hoc
clean	fastlane ios clean	Limpa build iOS

Gerais

Lane	Comando	Descrição
deploy_all	fastlane deploy_all	Deploy completo com TestFlight
build_all	fastlane build_all	Gera todos os builds sem upload

---

Algoritmo de Build

Fluxograma Android (AAB)

Fluxograma iOS (TestFlight)

---

Implementação Técnica

Fastfile - Android Lane

Lane: android aab - Código Completo

# fastlane/Fastfile

platform :android do
  desc "Gera AAB (App Bundle) assinado para Release"
  lane :aab do
    # Executa task Gradle para gerar bundle
    gradle(
      task: "bundle",
      build_type: "Release",
      project_dir: "android"
    )

    # Copia AAB para raiz do projeto
    sh("cp",
       "../android/app/build/outputs/bundle/release/app-release.aab",
       "../vidyaforce-release.aab")

    # Mensagens de sucesso
    UI.success("✅ AAB gerado com sucesso!")
    UI.important("📦 Localização: vidyaforce-release.aab")
  end
end

Fastfile - iOS Lane

Lane: ios deploy_testflight - Código Completo

# fastlane/Fastfile

platform :ios do
  desc "Build e upload para TestFlight"
  lane :deploy_testflight do
    # Incrementa build number automaticamente
    increment_build_number(
      xcodeproj: "ios/vidyaforce.xcodeproj"
    )

    # Instala/atualiza CocoaPods
    cocoapods(
      clean_install: true,
      podfile: "ios/Podfile"
    )

    # Gera o IPA
    build_app(
      workspace: "ios/vidyaforce.xcworkspace",
      scheme: "vidyaforce",
      export_method: "app-store",
      output_directory: "./build",
      output_name: "vidyaforce.ipa",
      clean: true,
      export_options: {
        method: "app-store",
        signingStyle: "manual",
        teamID: "9T529Y7MHF",
        provisioningProfiles: {
          "br.com.vidyacode.force" => "br.com.vidyacode.force AppStore"
        }
      }
    )

    # Mensagens informativas
    UI.success("✅ IPA gerado com sucesso!")
    UI.important("📦 Localização: build/vidyaforce.ipa")
    UI.important("🚀 Para enviar ao TestFlight:")
    UI.important("   1. Abra o app Transporter (Mac App Store)")
    UI.important("   2. Arraste o arquivo build/vidyaforce.ipa")
    UI.important("   3. Clique em 'Deliver'")
  end
end

Scripts NPM

// package.json

{
  "scripts": {
    // Android
    "deploy:android:apk": "bundle exec fastlane android apk",
    "deploy:android:aab": "bundle exec fastlane android aab",
    "deploy:android": "bundle exec fastlane android build_all",

    // iOS
    "deploy:ios:build": "bundle exec fastlane ios build",
    "deploy:ios:testflight": "bundle exec fastlane ios deploy_testflight",
    "deploy:ios:adhoc": "bundle exec fastlane ios adhoc",

    // Gerais
    "deploy:all": "bundle exec fastlane deploy_all",
    "build:all": "bundle exec fastlane build_all"
  }
}

---

Assinatura de Código

Android - Keystore

Localização Esperada

android/app/signature.keystore

Configuração no Gradle

// android/app/build.gradle

android {
    signingConfigs {
        release {
            storeFile file('signature.keystore')
            storePassword System.getenv("KEYSTORE_PASSWORD")
            keyAlias System.getenv("KEY_ALIAS")
            keyPassword System.getenv("KEY_PASSWORD")
        }
    }

    buildTypes {
        release {
            signingConfig signingConfigs.release
            // outras configurações...
        }
    }
}

Segurança

Nunca commite o arquivo .keystore no Git. Use variáveis de ambiente para senhas.

iOS - Provisioning Profiles

Métodos de Assinatura

Método	Uso	Configuração
Automatic	Desenvolvimento	CODE_SIGN_STYLE=Automatic
Manual	Produção	Provisioning Profile específico

Configuração Manual

# fastlane/Fastfile

export_options: {
  method: "app-store",
  signingStyle: "manual",
  teamID: "XXXXXXXXXX",
  provisioningProfiles: {
    "com.suaempresa.seuapp" => "Nome do Provisioning Profile"
  }
}

---

Versionamento Automático

Incrementar Build Number (iOS)

# Automaticamente incrementa CFBundleVersion
increment_build_number(
  xcodeproj: "ios/vidyaforce.xcodeproj"
)

# Com número específico
increment_build_number(
  xcodeproj: "ios/vidyaforce.xcodeproj",
  build_number: 550
)

Incrementar Version Name (Android)

# Editar manualmente em:
# android/app/build.gradle

android {
    defaultConfig {
        versionCode 550
        versionName "5.1.550"
    }
}

---

Troubleshooting

Problemas Comuns

Android

Problema	Causa	Solução
Keystore not found	Arquivo .keystore ausente	Adicione keystore em android/app/
Gradle build failed	Cache corrompido	Execute npm run clean:android
Duplicate resources	Assets duplicados	Limpe pasta android/app/src/main/res/

# Limpar build Android
npm run clean:android

# Ou manualmente
cd android
./gradlew clean
cd ..

iOS

Problema	Causa	Solução
No provisioning profile	Perfil ausente/expirado	Atualize em developer.apple.com
CocoaPods error	Dependências desatualizadas	Execute cd ios && pod install
Signing failed	Team ID incorreto	Verifique Appfile e Xcode

# Limpar build iOS
npm run clean:ios

# Ou manualmente
cd ios
xcodebuild clean
rm -rf build Pods
pod install
cd ..

Logs de Erro

Visualizar Log Completo

# Última execução
cat fastlane/report.xml

# Log em tempo real
bundle exec fastlane android aab --verbose

---

Boas Práticas

Checklist de Deploy

Antes do Build

• Atualizar versão no package.json
• Atualizar versionName e versionCode (Android)

Após o Build

• Testar instalação do APK/IPA
• Verificar tamanho do arquivo
• Validar funcionalidades críticas
• Documentar versão no sistema de controle

Segurança

Dados Sensíveis

Nunca exponha em código:

• Senhas de keystore
• Apple ID e senha
• Tokens de API
• Provisioning profiles

Use variáveis de ambiente ou serviços de secrets management.

Otimização de Build

# Limpar caches antes de build importante
npm run cc                  # Metro cache
npm run clean:android       # Android build
npm run clean:ios           # iOS build
npm run reset               # Reinstalar node_modules

---

Documentação Adicional

Recursos Úteis

Recurso	Link
Documentação Fastlane	docs.fastlane.tools
React Native Builds	reactnative.dev/docs/signed-apk-android
App Store Connect	appstoreconnect.apple.com
Google Play Console	play.google.com/console

Comandos Rápidos

# Ver todas as lanes disponíveis
bundle exec fastlane lanes

# Executar lane específica
bundle exec fastlane [platform] [lane]

# Exemplo: Android APK
bundle exec fastlane android apk

# Exemplo: iOS TestFlight
bundle exec fastlane ios deploy_testflight

# Com logs detalhados
bundle exec fastlane android aab --verbose

---