Como configurar o fastlane em um servidor de build Mac dedicado

O que você precisa antes

• Um Mac com Xcode, acesso de administrador e Homebrew.
• Um agente de CI nesse Mac: GitHub Actions, GitLab, Buildkite, Jenkins ou CircleCI.
• Uma conta no App Store Connect com permissão para criar API keys.
• Um repositório Git privado para o match, ou um bucket do Google Cloud ou do S3.

1. Instale o fastlane

A documentação do fastlane, lida em outubro de 2026, prefere o Bundler. Ela suporta Ruby 3.2 ou mais novo e prefere 3.3 ou mais novo. Ela desaconselha o Ruby do sistema do macOS. Instale um Ruby atual com um gerenciador de versões como o rbenv. Depois adicione um Gemfile ao projeto:

source "https://rubygems.org"

gem "fastlane"

gem install bundler
bundle update
git add Gemfile Gemfile.lock

O Bundler fixa a versão do fastlane no Gemfile.lock. Toda máquina e toda execução de CI usam a mesma. Rode como bundle exec fastlane.

O caminho mais simples em um único servidor de build é o Homebrew. Ele traz o próprio Ruby:

brew install fastlane

Escolha um caminho por projeto. Misturar os dois é como duas versões do fastlane acabam na mesma máquina.

2. Crie uma API key do App Store Connect

O fastlane recomenda API keys em vez de login com Apple ID: sem pedido de autenticação em dois fatores, mais velocidade e mais confiabilidade. No App Store Connect, abra Users and Access, depois Integrations, depois App Store Connect API. Crie uma Team Key. O fastlane avisa que chamadas de provisioning precisam de uma team key. Dê a ela o menor papel que funcione. Anote o Issuer ID e o Key ID. Baixe o arquivo .p8 na hora, porque a Apple só deixa baixar uma vez.

mkdir -p ~/.appstoreconnect
mv ~/Downloads/AuthKey_ABC123XYZ.p8 ~/.appstoreconnect/
chmod 600 ~/.appstoreconnect/AuthKey_ABC123XYZ.p8

Guarde a chave no Mac de build ou no cofre de segredos do seu CI. Nunca faça commit dela.

3. Configure o match uma vez, em uma máquina de desenvolvimento

bundle exec fastlane match init
bundle exec fastlane match development
bundle exec fastlane match appstore

O match init pergunta onde guardar os certificados e cria um Matchfile. Os dois comandos seguintes criam certificados e perfis e salvam tudo, criptografado, nesse armazenamento. Escolha uma senha forte. O CI lê essa senha da variável MATCH_PASSWORD.

O fastlane recomenda o modo readonly em todo sistema de CI. Assim o CI só baixa o que existe e nunca cria nem revoga nada.

4. Escreva as lanes

default_platform(:ios)

platform :ios do
  lane :test do
    run_tests(
      scheme: "MyApp",
      devices: ["iPhone 17"],
      result_bundle: true
    )
  end

  lane :beta do
    setup_ci
    api_key = app_store_connect_api_key(
      key_id: ENV["ASC_KEY_ID"],
      issuer_id: ENV["ASC_ISSUER_ID"],
      key_filepath: ENV["ASC_KEY_PATH"]
    )
    match(type: "appstore", readonly: is_ci, api_key: api_key)
    increment_build_number(
      build_number: latest_testflight_build_number(api_key: api_key) + 1
    )
    build_app(scheme: "MyApp")
    upload_to_testflight(api_key: api_key, skip_waiting_for_build_processing: true)
  end
end

O setup_ci cria um keychain temporário, muda o match para readonly e configura os caminhos de log e de resultados de teste. Ele só age quando o fastlane detecta uma execução de CI. Se a sua não for detectada, passe force: true. Pular o processamento do build termina o job mais cedo, mas o fastlane avisa que isso também pula a distribuição para testadores externos.

5. Chame pelo CI

Todo sistema de CI roda as mesmas linhas de shell. Guarde os segredos no seu CI, não no repositório.

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
bundle install
bundle exec fastlane beta
# needs MATCH_PASSWORD, ASC_KEY_ID, ASC_ISSUER_ID and ASC_KEY_PATH set as CI secrets

No GitHub Actions essas linhas vão em uma etapa run, com os segredos passados como env. Um Mac da MacRun já vem com o software de runner do GitHub Actions instalado. Nosso guia de configuração de iOS no GitHub Actions mostra um workflow completo. No GitLab, Buildkite ou CircleCI, coloque as mesmas linhas no script do job. No Jenkins, use uma etapa sh.

Como isso sobrevive a reinicializações

O fastlane não é um serviço. Ele roda dentro do job do seu agente de CI. O que precisa sobreviver a uma reinicialização é o agente e a sessão de login dele. Configure o agente como LaunchAgent com login automático, como nos nossos guias de GitLab Runner e Buildkite. O keychain temporário do setup_ci é recriado a cada execução. Um keychain de login bloqueado depois de reiniciar não consegue travá-lo.

Erros comuns e soluções

Estes são documentados pelo fastlane.

• Erros estranhos de codificação ou travamentos no CI. O fastlane precisa de um locale UTF-8. Defina LANG e LC_ALL como en_US.UTF-8.
• O job trava em um pedido de autenticação em dois fatores. Use a API key. Com um Apple ID, defina SPACESHIP_ONLY_ALLOW_INTERACTIVE_2FA para que ele falhe logo.
• O match tenta criar certificados novos no CI. Use readonly, ou chame setup_ci antes.
• O match não consegue clonar o repositório. O GitHub não aceita a mesma deploy key em dois repositórios. Use uma conta de máquina somente leitura, ou git_private_key, ou MATCH_GIT_BASIC_AUTHORIZATION.
• Os perfis estão instalados, mas o Xcode não vê. O Xcode 16 mudou a pasta de perfis. O fastlane segue o Xcode selecionado, então rode xcode_select antes do match em máquinas com dois Xcodes.

Por que um Mac dedicado ajuda

build_app e run_tests são builds do Xcode. Em uma máquina que mantém o DerivedData e as gems instaladas, eles são muito mais rápidos. No nosso benchmark com o app iOS da Wikipedia no Xcode 26.6, um build limpo levou 86 segundos em um M6. Ele levou 183 segundos em um runner macos-26 hospedado pelo GitHub. Um job depois de uma pequena mudança levou 27 segundos aquecido, contra 269 do zero.

Quando você não precisa de um servidor de build

Se você envia para o TestFlight uma vez por semana, um runner hospedado ou o Xcode Cloud dá menos trabalho. Veja nosso guia de alternativa ao Xcode Cloud para essa troca. Saiba também o que a MacRun não faz. Não cuidamos da assinatura de código para você. Você mesmo roda o match, como nesta página. Também não oferecemos SLA.

Pronto para um servidor de build? A página de preços lista todos os planos, e a documentação de configuração mostra como se conectar.