Assinatura de iOS na nuvem: um certificado novo a cada build e a solução
Por Nesim Razon, desenvolvedor mobile independente · 2026-11-18
Nossos builds para iPhone rodam na nuvem, porque desenvolvemos no Windows. O primeiro pipeline que funcionou assinava o app automaticamente e deu certo, até deixar de dar. Cada execução criava em silêncio mais um certificado na conta de desenvolvedor, e um dia os builds passaram a falhar por falta da chave privada. Isto é o que acontecia e a configuração que a substituiu.
O sintoma: certificados se acumulando
Com a assinatura gerenciada na nuvem durante a etapa de arquivamento, o build pede à API do App Store Connect o que precisa. No nosso caso isso significava um novo certificado Apple Development, com a nota Created via API, a cada build. Eles se acumulam rápido. A conta tem um limite de certificados de cada tipo, e chegamos a ele por volta do décimo primeiro.
Depois apareceu a segunda falha: a etapa de arquivamento reclamava que a chave privada não estava instalada. Um certificado sem a chave privada correspondente na máquina não serve para nada, e uma máquina de build nova nunca tem a chave de um certificado criado por uma máquina anterior.
O atalho tentador que falha depois
A ideia óbvia é arquivar sem assinar e assinar na exportação. O arquivamento funciona, a exportação até gera um pacote, e o App Store Connect rejeita o envio com um erro de assinatura inválida, o número 90035. O motivo é que os frameworks embutidos no app ficam sem assinatura quando o arquivo foi construído com a assinatura de código desligada. Não basta assinar só o app externo: cada framework embutido precisa da sua própria assinatura.
Então aqui não há atalho. O arquivo precisa ser assinado corretamente, com um certificado cuja chave privada esteja presente na máquina de build.
A configuração estável: uma chave de distribuição que você guarda
A solução é parar de deixar cada build inventar a própria identidade. Você cria um único certificado de distribuição, guarda a chave privada em segurança fora do serviço de nuvem e entrega ao build a mesma chave todas as vezes. O build então pede à API o certificado e o perfil de provisionamento, e a API devolve o certificado que já tem para aquela chave em vez de criar um novo.
No nosso pipeline a chave privada fica codificada em base64 em um grupo de variáveis secretas, ao lado da chave de API do App Store Connect e dos seus dois identificadores. Durante o build ela é decodificada para um arquivo e verificada com o openssl, de modo que um segredo danificado falha no primeiro minuto e não no fim de um build longo.
Os passos, em ordem
- Reconstruir o arquivo da chave de API como um PEM limpo: segredos costumam chegar com as quebras de linha estragadas, então retire o cabeçalho e o rodapé, os espaços e as sequências literais de barra invertida e n, quebre o corpo em linhas de 64 caracteres e verifique com o openssl.
- Definir o número do build no projeto e no Info.plist e imprimi-lo de novo a partir do pacote final antes de enviar.
- Decodificar a chave privada de distribuição a partir do segredo e verificá-la com o openssl.
- Inicializar o chaveiro na máquina de build.
- Buscar os arquivos de assinatura do identificador do pacote com a opção de criar, do tipo iOS App Store. A ferramenta reaproveita o certificado que pertence à sua chave.
- Adicionar os certificados ao chaveiro e depois aplicar os perfis de provisionamento ao projeto do Xcode.
- Gerar o ipa assinado a partir do projeto e do esquema e publicá-lo no TestFlight.
Economizando minutos
Os minutos de build no macOS são limitados em um plano gratuito, e cada execução de assinatura que falha gasta uma parte deles. Dois hábitos ajudam. O primeiro é iniciar o fluxo de assinatura só manualmente, para que um envio não gaste minutos. O segundo é manter um fluxo de simulador separado, que compila sem assinar e nunca fala com a Apple. Ele encontra rápido os erros de compilação comuns e não custa nada em certificados.
Também rodamos no Windows, antes de qualquer build na nuvem, um script que confere o projeto em busca de erros que já pagamos uma vez. Uma regra de um segundo vale mais do que um build de dez minutos.
O que levar daqui
- A assinatura automática na nuvem serve para um primeiro experimento, mas cria um certificado novo a cada execução.
- Um arquivo sem assinatura assinado na exportação deixa os frameworks sem assinatura e falha na validação do envio.
- Crie um único certificado de distribuição, guarde a chave privada com cópia de segurança e passe-a a cada build como segredo.
- Valide os segredos no início do build e imprima os números de versão a partir do pacote final.
Perguntas frequentes
Por que os builds falharam por falta da chave privada?
Cada execução criou um certificado novo em uma máquina nova, e a chave privada de um certificado só existe na máquina que o criou.
Posso arquivar sem assinar e assinar depois?
Não de forma confiável. Os frameworks embutidos ficam sem assinatura e o App Store Connect rejeita o envio por assinatura inválida.
Onde a chave privada de distribuição deve ficar?
Em um backup seguro que você controla e no serviço de CI como variável secreta, nunca no repositório.
Preciso de um Mac para configurar isso?
Não. A solicitação de certificado e a chave podem ser criadas em qualquer máquina, e o build na nuvem faz o resto.
Mais do blog
- O número de build do iOS que ficou em 1: três correções que falharam e uma que funcionou
- Porta de região do Analytics no iOS quando o país do chip não pode ser lido
- Por que meu link da App Store deu 404 e a página mostrava capturas de 2018
- Diretriz 2.1 da App Store "Information Needed": o que enviei
- Capturas de tela da App Store sem celular: Robolectric, um carregador de imagens falso e um navegador sem interface
- Um código QR para duas lojas de apps: uma pequena página de redirecionamento