Match (Fastlane): o que é, gerenciamento de certificados e configuração no desenvolvimento

O que é Match (Fastlane)?

Match (Fastlane) é um componente do ecossistema Fastlane projetado para o gerenciamento centralizado de certificados Code Signing e perfis de provisionamento para desenvolvimento iOS. Ele resolve o problema de sincronização de assinaturas entre os membros da equipe e automatiza a configuração de certificados em pipelines CI/CD sem intervenção do desenvolvedor.

Sem o Match, cada membro da equipe gera manualmente certificados através do Xcode ou Apple Developer Portal, causando conflitos de compilação em diferentes máquinas. Code Signing é o processo de assinatura digital de um aplicativo iOS, que confirma sua autoria e integridade antes da instalação no dispositivo de um usuário.

De acordo com a Documentação para desenvolvedores da Apple (2025), a configuração incorreta de certificados é uma das causas mais comuns de rejeição ao enviar um aplicativo para a App Store. O Match verifica automaticamente a validade dos certificados e avisa sobre certificados prestes a expirar, reduzindo o risco de rejeição de compilação durante a etapa de verificação da Apple.

Use o Match em qualquer projeto com dois ou mais desenvolvedores ou quando tiver um pipeline CI/CD — ele reduz o tempo de configuração do ambiente de um novo membro da equipe de 30 minutos para um único comando no terminal.

Como o Match funciona: armazenamento Git criptografado

Arquitetura do Match é baseada no conceito de fonte única de verdade para todos os certificados da equipe iOS. Em vez do armazenamento local no keychain de cada desenvolvedor, o Match consolida os certificados em um único repositório Git com criptografia de cada arquivo antes do armazenamento.

O processo consiste em três etapas. Na etapa de inicialização, o Match gera todos os certificados e perfis necessários através da API do Apple Developer Portal. Cada arquivo é criptografado usando o algoritmo AES-256 com uma chave formada a partir de uma frase secreta definida pelo usuário. Os arquivos criptografados são salvos no repositório Git e sincronizados com o servidor remoto através de operações padrão Git push e pull.

Arquitetura de criptografia de certificados

O Match usa uma combinação de OpenSSL e uma frase secreta definida pelo usuário para criptografar certificados e perfis. A chave de acesso é definida através da variável de ambiente MATCH_PASSWORD e não é armazenada no repositório, evitando vazamentos mesmo se o servidor Git for comprometido ou o repositório for de acesso público.

Ao solicitar um certificado, o Match baixa o arquivo criptografado do repositório, descriptografa-o localmente usando a frase secreta e o instala no keychain da máquina atual. Após a conclusão da compilação, os certificados podem ser removidos do keychain para cumprir as políticas de segurança de ambientes corporativos — isso evita o uso de certificados obsoletos em compilações subsequentes.

Cada certificado é salvo com um nome contendo o identificador do aplicativo, o tipo de perfil e a data de criação. Essa estrutura permite que o Match gerencie versões de certificados e, se necessário, reverta alterações para um estado anterior usando comandos padrão Git revert e reset. Isso é especialmente útil quando um perfil é excluído ou sobrescrito acidentalmente.

Configuração do Match

O Match é instalado junto com o Fastlane através do gerenciador de pacotes Ruby: gem install fastlane. Após a instalação, inicialize o armazenamento de certificados com o comando fastlane match init, que cria um repositório Git vazio e gera um arquivo Matchfile com um modelo de configuração básica.

# Inicializar repositório do Match
fastlane match init

Configuração através do Matchfile

O arquivo Matchfile contém todos os parâmetros de conexão ao armazenamento de certificados: URL do repositório Git, tipo de perfil padrão, identificadores de aplicativo e credenciais do Apple Developer. Exemplo de uma configuração típica para uma equipe de cinco desenvolvedores:

# Configuração do Matchfile
git_url("https://github.com/company/certificates.git")
type(:development)
app_identifier(["com.company.app", "com.company.app.extension"])
username("developer@company.com")
team_id("TEAM123456")
git_branch("main")

O parâmetro type define o tipo de perfil: :development para depuração em dispositivos de desenvolvedores, :appstore para publicação na App Store, :adhoc para teste em dispositivos externos e :enterprise para distribuição corporativa In-House fora da App Store. Cada tipo cria um diretório separado no repositório, permitindo organizar os perfis por cenários de compilação alvo.

O Match suporta vários métodos de autenticação para o Apple Developer Portal: autenticação de dois fatores via Apple ID, senha específica de aplicativo (App-Specific Password) e chaves API do App Store Connect. Para CI/CD, recomenda-se o uso de chaves API — elas não exigem entrada interativa de código de confirmação e não bloqueiam compilações automatizadas quando o dispositivo do desenvolvedor muda.

Geração e sincronização de perfis

Após configurar o Matchfile, execute o comando fastlane match development ou fastlane match appstore para gerar e sincronizar perfis. O Match cria ou atualiza automaticamente os certificados através da API do Apple Developer Portal e os salva no repositório. Apple Developer Portal é a interface web da Apple para gerenciar certificados, identificadores de aplicativo e listas de dispositivos de desenvolvedores aprovados.

Na primeira execução, o Match solicitará uma frase secreta para criptografar o repositório. Esta frase deve ser armazenada no gerenciador de segredos do CI/CD (GitHub Actions Secrets, GitLab CI Variables ou Jenkins Credentials) e transmitida através da variável de ambiente MATCH_PASSWORD. Sem ela, o Match não conseguirá descriptografar os certificados em outras máquinas ou no ambiente CI.

Comandos básicos do Match para gerenciar certificados

Interface do Match consiste em um conjunto de comandos para criar, atualizar, sincronizar e excluir certificados e perfis. Cada comando corresponde a uma ação específica no ciclo de vida do Code Signing: desde a geração até a limpeza completa do repositório.

Comandos para o trabalho diário

O comando fastlane match development baixa ou cria certificados e perfis de desenvolvimento para depuração em dispositivos locais. Provisioning Profile é um documento digital da Apple que vincula um certificado de desenvolvedor a um identificador de aplicativo e a uma lista de dispositivos autorizados para instalação.

Para publicar na App Store, use fastlane match appstore — ele gera certificados de distribuição e perfis AppStore. O comando fastlane match adhoc cria perfis para teste em dispositivos externos, e fastlane match enterprise para aplicativos corporativos In-House.

# Criar perfis de Development para depuração
fastlane match development

# Criar perfis de AppStore para lançamento
fastlane match appstore

# Importar certificados existentes criados manualmente
fastlane match import

O comando fastlane match import permite adicionar certificados existentes ao repositório — útil ao migrar do gerenciamento manual para o Match. O parâmetro --readonly bloqueia qualquer alteração no repositório, o que é crítico para ambientes CI onde o pipeline não deve criar ou excluir certificados e perfis automaticamente.

Para uma limpeza completa do repositório, use o comando fastlane match nuke. Ele remove todos os certificados do armazenamento Git, do Apple Developer Portal e da máquina local — uma redefinição completa do estado do Code Signing para o projeto. O comando é usado apenas em conflitos críticos ou ao migrar para uma nova conta Apple Developer.

Integração do Match no pipeline CI/CD

Integração CI/CD do Match é uma das principais vantagens da ferramenta. Em pipelines do GitHub Actions, GitLab CI, Bitrise ou Jenkins, o Match baixa e instala automaticamente os certificados corretos sem envolvimento do desenvolvedor. Isso permite a compilação e assinatura totalmente automatizadas de aplicativos iOS do commit até um IPA pronto.

Uma configuração típica do GitHub Actions inclui instalar o Fastlane, configurar a variável MATCH_PASSWORD e executar o Match com a flag --readonly. GitHub Actions é a plataforma CI/CD do GitHub que automatiza a compilação, teste e publicação de código com base em eventos do repositório.

# Instalar Fastlane no ambiente CI
gem install fastlane --no-document

# Executar Match em modo somente leitura sem direitos de modificação
fastlane match development --readonly

Antes de executar o Match em CI, configure o acesso ao repositório de certificados. O Fastlane o clona automaticamente com base no parâmetro git_url do Matchfile. O acesso ao repositório é configurado através de uma chave SSH ou token de acesso pessoal, que são adicionados aos segredos do sistema CI — isso garante que os certificados não sejam comprometidos através de acesso público.

Defina as variáveis de ambiente MATCH_PASSWORD e FASTLANE_APPLE_API_KEY nos segredos do seu provedor de CI. A chave API do App Store Connect permite que o Match se autentique no Apple Developer Portal sem autenticação de dois fatores, eliminando solicitações interativas em compilações automatizadas e prevenindo o bloqueio do pipeline.

Erros comuns ao trabalhar com o Match

Mesmo com a configuração correta do Match, podem ocorrer erros relacionados a certificados expirados, conflitos de perfis ou configuração incorreta do ambiente. Diagnóstico de problemas do Match é baseado na análise de logs de comandos e na verificação do estado do repositório Git quanto à relevância dos certificados.

O erro mais comum — «You need to provide a password for Match» — ocorre quando a variável de ambiente MATCH_PASSWORD não está definida na máquina ou no ambiente CI. Solução: adicione MATCH_PASSWORD às variáveis de ambiente do sistema ou passe a senha através do parâmetro --keychain_password ao executar o comando Match.

O segundo problema mais frequente são conflitos de certificados ao adicionar um novo dispositivo a um perfil AdHoc. Ele é resolvido com o comando fastlane match adhoc --force, que recria os perfis levando em conta os novos dispositivos. Os certificados Apple Developer são válidos por um ano, após o qual as compilações que os utilizam são rejeitadas pelo App Store Connect. O Match avisa sobre a expiração 30 dias antes do final do período de validade.

Quando ocorre o erro «Multiple matches found for...», existem várias versões do mesmo certificado no repositório. Use o comando fastlane match nuke para limpar completamente o repositório e remover todos os certificados do Apple Developer Portal. Após a limpeza, realize uma geração do zero — isso garante um estado consistente dos perfis sem duplicatas ou versões conflitantes.