Lane — o que é, criação e uso no Fastlane

O que é um Lane no Fastlane

Lane é o bloco de construção fundamental do Fastlane que define um cenário de automação nomeado. Cada lane descreve uma sequência de ações executadas para atingir um objetivo específico: compilar um aplicativo, executar testes, enviar um build para a loja ou configurar o ambiente. Um lane é declarado no Fastfile e executado com o comando fastlane [nome_lane] a partir da raiz do projeto.

O conceito de lane é emprestado do Ruby DSL e garante a legibilidade dos cenários. O desenvolvedor vê todo o processo CI/CD como uma sequência de chamadas de ações com nomes e parâmetros claros. Um lane pode ser simples (um comando) ou complexo (ramificações, loops, chamadas a outros lanes).

Após a execução, cada lane retorna um resultado — um objeto contendo o status da execução e dados das ações. O resultado pode ser usado em outros lanes ou passado para o sistema CI/CD para tomada de decisões. Se alguma ação no lane falhar, a execução do lane é interrompida e o bloco error é invocado.

Sintaxe do lane: declaração e execução

A sintaxe de declaração de um lane segue um padrão simples de Ruby DSL: a palavra-chave lane, o nome do cenário como um símbolo Ruby e um bloco do ... end com o corpo do cenário. O nome do lane deve ser único dentro da plataforma e consistir em letras, dígitos e sublinhados.

Um lane é executado via linha de comando: fastlane build (para um lane chamado :build) ou bundle exec fastlane build (se o Fastlane estiver instalado via Bundler). Para lanes específicos de plataforma, use fastlane ios build ou fastlane android build.

# Declarar um lane simples
lane :test do
  scan(scheme: 'App', devices: ['iPhone 15'])
end

lane :build_and_deploy do
  cocoapods
  test
  gym(scheme: 'App', export_method: 'app-store')
  pilot(skip_waiting_for_build_processing: true)
end

# Executar: fastlane build_and_deploy

Um lane pode conter lógica condicional baseada em parâmetros ou variáveis de ambiente. Use if/unless para pular etapas sob certas condições. Loops (each) também estão disponíveis para processar arrays, o que é conveniente para compilar vários alvos ou esquemas de aplicativo em um único lane.

Retornar um valor de um lane

Um lane pode retornar um valor que estará disponível para o código chamador. Para retornar um valor, use um return padrão do Ruby ou a última expressão no bloco do lane. O valor retornado pode ser uma string, número, hash ou o resultado de uma ação. Isso permite usar o resultado de um lane em outro lane para tomada de decisões.

Por exemplo, um lane :get_version pode retornar a versão atual do aplicativo do Info.plist, e o lane :deploy pode usá-la para compor uma mensagem no Slack. Os valores de retorno são especialmente úteis em private lanes, onde o resultado é necessário para processamento posterior no lane chamador.

Parâmetros de lanes: passagem e tratamento

Os parâmetros de lane tornam os cenários flexíveis e reutilizáveis. Um lane aceita parâmetros via hash options, que é passado ao executar da linha de comando: fastlane deploy scheme:AppStore version:2.1.0. Dentro do lane, os parâmetros estão disponíveis como options[:scheme] e options[:version].

Para parâmetros obrigatórios, verifique a presença do valor no início do lane e chame UI.user_error! com uma mensagem clara. Para parâmetros opcionais, defina valores padrão usando o operador ||. O Fastlane também suporta parâmetros tipados através do método options com tipo, valor padrão e descrição.

# Lane com tratamento de parâmetros
lane :deploy do |options|
  scheme = options[:scheme]
  version = options[:version] || '1.0.0'
  beta = options[:beta] || false

  UI.user_error!("scheme não especificado") unless scheme

  match(type: beta ? 'adhoc' : 'appstore')
  gym(scheme: scheme, export_method: beta ? 'ad-hoc' : 'app-store')

  if beta
    pilot(distribute_external: true)
  else
    deliver(submit_for_review: true)
  end
end

# Executar: fastlane deploy scheme:MyApp beta:true version:2.1.0

Para trabalhar com variáveis de ambiente dentro de um lane, use ENV['VARIABLE_NAME']. O Fastlane carrega automaticamente os arquivos .env do diretório fastlane. Esta é a forma padrão de passar dados sensíveis — chaves de API, senhas e tokens — em um ambiente CI/CD sem armazená-los no Fastfile.

Validação de parâmetros

Para uma operação confiável do lane, a validação de parâmetros na entrada é necessária. Use UI.user_error! com uma descrição do problema se um parâmetro obrigatório estiver faltando ou tiver um tipo incorreto. O Fastlane fornece o método options, que permite especificar o tipo (String, Boolean, Integer, Array), valor padrão e descrição para cada parâmetro — a validação é realizada automaticamente quando o lane é iniciado.

Adicionalmente, você pode usar verificações através de um bloco verify: verify do |value| value.length > 0 end para parâmetros de string. Se o formato estiver incorreto, o Fastlane exibe uma mensagem clara indicando o formato esperado e o valor fornecido, simplificando a depuração em um ambiente CI/CD.

Combinação de lanes: before_all, after_all e tratamento de erros

O Fastlane fornece hooks de ciclo de vida para executar código antes e depois de cada lane. O bloco before_all é executado antes de cada lane em uma determinada plataforma ou globalmente. O bloco after_all é executado após a conclusão bem-sucedida de um lane. O bloco error é executado em qualquer erro dentro de um lane.

Os hooks permitem centralizar a lógica repetitiva: configuração de dependências no before_all, envio de notificações no after_all, limpeza de arquivos temporários e notificação de erros no bloco error. Isso reduz a duplicação de código e mantém os lanes mais limpos.

# Hooks de ciclo de vida de lanes
default_platform(:ios)

before_all do
  cocoapods(try_repo_update_on_error: true)
  ensure_git_status_clean
end

after_all do |lane|
  slack(message: "Lane #{lane} executado com sucesso")
end

error do |lane, exception|
  slack(
    message: "Lane #{lane} falhou com erro: #{exception}",
    success: false
  )
end

lane :deploy do
  match(type: 'appstore')
  gym(export_method: 'app-store')
  deliver
end

O bloco error recebe dois argumentos: o nome do lane (símbolo) e o objeto de exceção. Dentro do bloco, você pode enviar uma notificação para o Slack, escrever um log em um arquivo ou executar um cenário de recuperação alternativo. Se o bloco error for concluído com sucesso, o Fastlane não considera o build como falhado no nível CI/CD.

Private lanes e reutilização

Um private lane é um lane declarado com private_lane em vez de lane, que não aparece na lista de comandos disponíveis e não pode ser executado diretamente do terminal. Os private lanes são projetados para encapsular etapas repetitivas chamadas de vários lanes públicos.

Os private lanes são especialmente úteis para sequências complexas de ações que devem ser executadas em uma ordem estritamente definida. Por exemplo, um private lane :setup_signing pode ser chamado dos lanes :build_dev, :build_staging e :build_production com diferentes parâmetros, mas por si só não faz sentido como um comando separado.

# Private lanes para reutilização
private_lane :setup_environment do |options|
  cocoapods(try_repo_update_on_error: true)
  match(type: options[:type], readonly: true)
  increment_build_number
end

lane :dev_build do
  setup_environment(type: 'development')
  gym(export_method: 'development')
end

lane :appstore_build do
  setup_environment(type: 'appstore')
  gym(export_method: 'app-store')
  deliver
end

Private lanes podem chamar outros private lanes, formando uma hierarquia de abstração. Recomenda-se limitar a profundidade de aninhamento a 2–3 níveis para manter a legibilidade do Fastfile. Documente cada private lane com um comentário descrevendo seu propósito e os parâmetros esperados.

Exemplos de lanes para iOS e Android

Vejamos exemplos práticos de lanes para projetos iOS e Android. Lanes iOS geralmente usam scan para testes, match para certificados, gym para compilação e pilot ou deliver para distribuição. Lanes Android usam gradle para compilação, supply para publicação e firebase_test_lab para testes em nuvem.

// Lane para CI/CD completo de app iOS
lane :ci_full_ios do
  scan(scheme: 'App', code_coverage: true)
  gym(scheme: 'App', export_method: 'app-store')
  pilot(distribute_external: true)
  slack(message: 'CI/CD iOS concluído com sucesso')
end

/* Lane para CI/CD completo de app Android */
lane :ci_full_android do
  gradle(task: 'testReleaseUnitTest')
  gradle(task: 'bundleRelease')
  supply(track: 'internal')
end

Ao combinar lanes para iOS e Android, você pode criar um processo CI/CD unificado para um aplicativo multiplataforma. Use os blocos de plataforma platform :ios e platform :android para agrupar lanes específicos de cada plataforma e chame-os de um lane orquestrador comum que gerencia a ordem de execução.

Melhores práticas para escrever lanes

Ao escrever lanes, recomenda-se seguir um conjunto de práticas que garantem legibilidade, manutenibilidade e confiabilidade dos cenários. A primeira regra é que cada lane deve realizar uma tarefa. Se um lane faz muito, divida-o em vários lanes e private lanes.

A segunda regra é que a nomeação do lane deve ser um verbo ou frase verbal: build, deploy, test, upload_screenshots. Evite nomes abstratos como process ou do_all. Use sublinhados para separar palavras no nome do lane.

A terceira regra é tratar erros explicitamente. Use UI.user_error! para mensagens de problema claras. Não confie nas mensagens de erro padrão do Fastlane — dê contexto ao desenvolvedor: “Arquivo GoogleService-Info.plist não encontrado — adicione-o ao projeto” em vez de “Arquivo não encontrado”.

A quarta regra é testar lanes localmente antes de executar em CI/CD. O Fastlane suporta o modo dry-run através da flag --dry-run, que mostra quais ações serão executadas sem realmente executá-las. Use fastlane run_test para testes isolados de lanes individuais antes da integração.

Documentação de lanes

Documentar cada lane é uma prática importante para o desenvolvimento em equipe. O Fastlane suporta a geração automática de documentação a partir do bloco desc colocado antes da declaração do lane. O texto desc é exibido ao executar fastlane lanes e fastlane list, ajudando os desenvolvedores a entender o propósito de cada cenário sem ler o código fonte do Fastfile.

Para documentar os parâmetros, use comentários Ruby com a descrição dos valores esperados. O Fastlane pode gerar um README.md com a lista completa de lanes e suas descrições através do comando fastlane generate_docs, o que é conveniente para a integração de novos membros da equipe aos processos CI/CD do projeto.