Fastfile: essência, estrutura e configuração da automação no desenvolvimento móvel

O que é Fastfile e por que você precisa dele

Fastfile é o principal arquivo de configuração do Fastlane, escrito em Ruby e localizado no diretório fastlane na raiz do projeto. Ele define todos os cenários de automação (lanes) para compilar, testar, assinar código e entregar o aplicativo. O Fastfile substitui dezenas de scripts bash, Makefiles e instruções manuais por uma única descrição declarativa de pipeline CI/CD.

A necessidade do Fastfile surge quando um projeto requer compilações reproduzíveis em diferentes máquinas de desenvolvedores e servidores CI/CD. Em vez de cada desenvolvedor configurar o ambiente manualmente, o Fastfile captura todas as etapas em código que pode ser versionado no Git, revisado e reutilizado entre projetos. Um único Fastfile garante que a compilação na máquina do desenvolvedor seja idêntica à compilação no servidor CI/CD.

O Fastfile suporta plataformas através da diretiva default_platform. Em um único Fastfile é possível descrever cenários para iOS, Android e macOS, agrupando-os em blocos platform :ios e platform :android. Isso é especialmente útil para projetos multiplataforma onde as compilações iOS e Android compartilham lógica de implantação comum, mas usam ferramentas de compilação diferentes.

Estrutura do Fastfile: lanes, actions e parâmetros

O Fastfile consiste em três elementos principais: declaração de plataforma (default_platform), definição de lanes e configuração de funções auxiliares. Cada lane começa com a palavra-chave lane, seguida pelo nome do cenário (símbolo Ruby), o corpo com uma sequência de ações e blocos de tratamento de erros: error, success ou ensure.

As actions no Fastfile são chamadas para funções integradas do Fastlane com parâmetros na forma de Hash. Por exemplo, gym(scheme: 'App', export_method: 'app-store') inicia uma compilação iOS com os parâmetros especificados. Cada action retorna um resultado que pode ser armazenado em uma variável e usado em actions subsequentes — isso permite lógica condicional dentro de uma lane.

O Fastfile suporta variáveis de ambiente através do mecanismo padrão ENV do Ruby. Dados sensíveis (senhas, tokens, chaves) não devem ser armazenados no Fastfile — use variáveis de ambiente do sistema CI/CD ou um arquivo .env adicionado ao .gitignore. O Fastlane carrega automaticamente os arquivos .env do diretório fastlane na inicialização.

Appfile e Matchfile

Junto com o Fastfile, no diretório fastlane estão localizados arquivos de configuração adicionais. O Appfile contém identificadores do aplicativo (app_identifier), Apple ID e Team ID — esses dados são automaticamente substituídos em todas as actions, eliminando a repetição em cada lane. O Matchfile armazena as configurações para match: a URL do repositório Git, o tipo de perfis e a chave de criptografia.

Dividir a configuração em vários arquivos simplifica a manutenção de projetos com diferentes ambientes. Por exemplo, para staging e produção, você pode criar branches separadas no repositório do Matchfile ou substituir parâmetros através de variáveis de ambiente no sistema CI/CD.

# Estrutura básica do Fastfile
default_platform(:ios)

lane :build_and_test do
  cocoapods
  scan(scheme: 'App', devices: ['iPhone 15'])
  gym(scheme: 'App')
end

lane :deploy do
  match(type: 'appstore')
  build_and_test
  pilot(skip_waiting_for_build_processing: true)
end

Sintaxe do Fastfile: escrevendo lanes

A sintaxe do Fastfile é baseada em Ruby DSL (Domain Specific Language), projetada especificamente para a legibilidade de cenários de automação. Uma lane é declarada através da construção lane :name do ... end, onde name é um símbolo Ruby que se torna o comando fastlane name para executar a partir do terminal ou sistema CI/CD.

Dentro de uma lane você pode usar operadores condicionais do Ruby: if, unless, case para ramificar a lógica. Os loops each e while também estão disponíveis para processar arrays de valores. O Fastlane fornece métodos especiais before_all, after_all e blocos error para lidar com eventos do ciclo de vida da lane.

Os parâmetros de lane são passados através do hash options. Ao executar fastlane build --option_name value, o valor vai para options[:option_name] dentro da lane. Você pode definir valores padrão através de optional: true e validação de tipo para controlar os tipos de parâmetros passados.

# Lane com parâmetros e lógica condicional
lane :build do |options|
  scheme = options[:scheme] || 'App'
  export_method = options[:export_method] || 'development'

  match(type: export_method)

  if export_method == 'appstore'
    gym(scheme: scheme, export_method: 'app-store')
    pilot(skip_waiting_for_build_processing: true)
  else
    gym(scheme: scheme, export_method: export_method)
  end
end

Exemplo de Fastfile para entrega iOS

Um Fastfile completo para um projeto iOS inclui lanes para instalação de dependências, testes, compilação e implantação no TestFlight e App Store. Vamos ver um exemplo que cobre um processo CI/CD típico desde o commit até a publicação no TestFlight para testes internos.

# Fastfile para entrega CI/CD iOS
default_platform(:ios)

before_all do
  cocoapods(try_repo_update_on_error: true)
  setup_travis if ENV['TRAVIS']
end

lane :tests do
  scan(
    scheme: 'App',
    devices: ['iPhone 15', 'iPad Pro 12.9'],
    output_directory: './test_reports'
  )
end

lane :build_appstore do
  match(type: 'appstore', readonly: true)
  gym(
    scheme: 'App',
    export_method: 'app-store',
    include_bitcode: true
  )
end

lane :deploy_testflight do
  build_appstore
  pilot(
    skip_waiting_for_build_processing: true,
    distribute_external: false
  )
  slack(
    message: 'Compilação enviada ao TestFlight para testes internos'
  )
end

Neste exemplo, o bloco before_all é executado antes de cada lane e instala as dependências. A lane tests executa testes de UI e Unit em dois dispositivos. A lane build_appstore assina o código via match e compila o IPA com bitcode. A lane deploy_testflight combina todas as etapas para a entrega completa.

Implantação com múltiplos alvos

Projetos com múltiplos alvos (aplicativo principal, watchOS, widget, Notification Service Extension) requerem lanes separadas para cada alvo. No Fastfile você pode criar uma lane universal :deploy_target que aceita o nome do esquema e o caminho da compilação como parâmetros. Isso permite executar a implantação para todas as extensões via fastlane deploy_target scheme:Widget.

Para organizar múltiplos alvos, use um array de esquemas e um loop each dentro da lane. O Fastlane suporta compilação paralela de múltiplos esquemas através da flag parallel: true, o que reduz o tempo total do pipeline CI/CD para aplicativos com extensões.

Exemplo de Fastfile para compilação Android

O Fastfile para projetos Android usa a ação gradle para executar tarefas do Gradle e a ação supply para publicar no Google Play. Ao contrário do iOS, o Android não requer match, mas usa um Keystore para assinatura, que é armazenado fora do repositório e passado através de variáveis de ambiente.

# Fastfile para compilação CI/CD Android
default_platform(:android)

lane :build_release do
  gradle(task: 'clean')
  gradle(task: 'bundleRelease')
  gradle(task: 'assembleRelease')
end

lane :deploy_internal do
  build_release
  supply(
    track: 'internal',
    aab: 'app/build/outputs/bundle/release/app-release.aab',
    release_status: 'completed'
  )
end

Para a assinatura Android, configure signingConfigs no build.gradle e passe os parâmetros do Keystore através de variáveis de ambiente: ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS e ANDROID_KEY_PASSWORD. O Fastlane usa automaticamente o apksigner do sistema para assinar o AAB ou APK compilado.

Assinatura Android no Fastfile

Para configurar a assinatura Android no Fastfile, use a ação sign_android ou confie no signingConfigs no build.gradle. O Fastlane se integra com o apksigner através do Gradle — passar a flag SIGNING_CONFIG na tarefa gradle ativa a assinatura com parâmetros de variáveis de ambiente. Isso permite assinar arquivos AAB antes de enviá-los ao Google Play Console.

Para armazenamento seguro do Keystore em CI/CD, use codificação Base64 e variáveis de ambiente. O Fastlane suporta a ação setup_keystore, que decodifica o Keystore de uma variável e o salva em um arquivo temporário durante o estágio before_all. Após a conclusão da lane, o arquivo temporário é automaticamente excluído para evitar vazamento de certificados.

Uso de private lanes e grupos

As private lanes (cenários privados) são lanes que não podem ser chamadas diretamente da linha de comando, mas estão disponíveis para serem chamadas de outras lanes dentro do Fastfile. Uma private lane é declarada através da construção private_lane :name do ... end e é usada para encapsular etapas repetitivas que não fazem sentido como cenários independentes.

As private lanes são ideais para agrupar lógica repetitiva: instalação de dependências, configuração de ambiente, envio de notificações. Por exemplo, você pode criar uma private lane :setup_signing que é chamada de várias lanes de implantação, mas não deve estar disponível para execução direta pelo desenvolvedor para evitar erros.

# Private lane e agrupamento
default_platform(:ios)

private_lane :setup_signing do |options|
  match(
    type: options[:type],
    readonly: true,
    verbose: false
  )
end

lane :beta do
  setup_signing(type: 'adhoc')
  gym(export_method: 'ad-hoc')
  pilot(distribute_external: true)
end

lane :release do
  setup_signing(type: 'appstore')
  gym(export_method: 'app-store')
  deliver(
    force: true,
    submit_for_review: true
  )
end

O agrupamento de lanes através de blocos platform permite separar cenários iOS e Android em um mesmo Fastfile. A construção platform :ios do ... end e platform :android do ... end isola as lanes da plataforma correspondente, enquanto as private lanes comuns podem ser colocadas fora dos blocos de plataforma para reutilização.

Passagem de parâmetros para lanes

O mecanismo de parâmetros do Fastfile permite que as lanes sejam flexíveis e reutilizáveis. Os parâmetros são passados em tempo de execução através da linha de comando: fastlane build scheme:App export_method:appstore. Dentro da lane, os valores são acessíveis através do hash options, que é passado para o bloco da lane como argumento.

O Fastlane suporta parâmetros tipados com validação através de OptionalHash. Você pode especificar o tipo de valor (String, Boolean, Integer), um valor padrão e uma descrição para geração automática de documentação. As variáveis de ambiente também estão disponíveis como forma alternativa de passar parâmetros, o que é conveniente para sistemas CI/CD.

# Parâmetros com validação de tipos
lane :build do |options|
  gym(
    scheme: options[:scheme],
    export_method: options[:export_method] || 'development',
    include_bitcode: options[:include_bitcode] || false,
    output_name: options[:output_name]
  )
  slack(message: "Compilação #{options[:scheme]} concluída")
end

# Execução: fastlane build scheme:MyApp export_method:appstore

Recomenda-se usar valores padrão para todos os parâmetros opcionais, para que uma lane possa ser executada sem especificar explicitamente cada argumento. Para parâmetros obrigatórios, verifique sua presença no início da lane e interrompa a execução com uma mensagem de erro clara através de UI.user_error!.