Como rodar um agente Buildkite em um Mac

O que você precisa antes

• Um cluster no Buildkite e permissão para gerenciar os tokens de agente e as filas dele. Você precisa ser administrador da organização ou mantenedor do cluster.
• Um Mac com macOS 11 ou mais novo. Esse é o mínimo informado pelo Buildkite. Apple silicon, Homebrew, Xcode e acesso de administrador.
• Uma chave SSH que o agente possa usar para clonar os seus repositórios.

1. Crie uma fila e um token de agente

No Buildkite, selecione Agents para chegar à página Clusters e escolha o seu cluster. Na página Queues, selecione New Queue. Dê a ela a chave macos e escolha Self hosted. Depois abra Agent Tokens, selecione New Token, adicione uma descrição e crie o token. Copie o valor. O Buildkite mostra o token uma única vez.

O formulário do token tem um campo Allowed IP Addresses. Deixe vazio na MacRun. Nossos Macs não têm IP público fixo, então uma regra CIDR deixaria o agente de fora.

2. Instale o agente com Homebrew

brew tap buildkite/buildkite
brew trust buildkite/buildkite
brew install buildkite/buildkite/buildkite-agent

O Homebrew 7.0.7, a versão no nosso Mac em outubro de 2026, recusa fórmulas de um tap de terceiros até você confiar nele. É a linha do meio. A fórmula agora se chama buildkite-agent@3, e o nome antigo da documentação do Buildkite ainda aponta para ela.

No Apple silicon os arquivos ficam em /opt/homebrew:

• Configuração: /opt/homebrew/etc/buildkite-agent/buildkite-agent.cfg
• Hooks: /opt/homebrew/etc/buildkite-agent/hooks
• Log: /opt/homebrew/var/log/buildkite-agent.log

Rode brew info buildkite-agent para ver os caminhos exatos na sua máquina.

3. Adicione o token e a tag de fila

A documentação do Buildkite usa sed para trocar o token de exemplo. Substitua o texto em maiúsculas pelo seu token.

sed -i '' "s/xxx/INSERT-YOUR-AGENT-TOKEN-HERE/g" "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg
cat "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg | grep token

Depois abra o mesmo arquivo e defina a linha de tags, para que o agente entre na sua fila:

tags="queue=macos"

Um agente pertence a uma fila auto-hospedada em um cluster. Sem tag de fila, ele entra na fila padrão. Se o cluster não tiver uma fila auto-hospedada padrão, o Buildkite diz que o agente não consegue se conectar.

4. Teste e depois rode como serviço

Inicie uma vez em primeiro plano. Ele deve aparecer na lista de agentes do cluster.

buildkite-agent start

Pare com Control C. A fórmula do Homebrew traz uma definição de serviço. Ela roda buildkite-agent start com a configuração acima, reinicia em caso de falha e grava no mesmo arquivo de log. Inicie no Terminal na área de trabalho do Mac:

brew services start buildkite/buildkite/buildkite-agent@3
brew services list | grep buildkite

No macOS, o agente roda com o usuário que iniciou o serviço do launchd. Inicie com a conta dona do Xcode e das suas chaves de assinatura.

Comece com um agente por Mac. O Buildkite documenta uma opção spawn no arquivo de configuração, e uma flag --spawn, para rodar vários agentes em um serviço. Dois builds do Xcode ao mesmo tempo disputam os mesmos núcleos e a mesma memória. Em uma máquina de 16 GB, meça um agente primeiro e depois teste dois.

5. Faça ele sobreviver a uma reinicialização

As próprias notas de instalação da fórmula dizem para configurar o Mac para entrar automaticamente com esse usuário. O README do tap do Buildkite explica a troca. Um LaunchAgent precisa de um login, mas deixa os testes usarem ferramentas gráficas como o Simulador do iOS. Ative o login automático em System Settings, em Users and Groups. Depois desligue o repouso, reinicialize e confira a lista de agentes.

sudo pmset -a sleep 0
sudo shutdown -r now

Deixe o plist na pasta LaunchAgents da sua pasta pessoal, que é onde o Homebrew coloca. No macOS 27 vimos um plist em /Library/LaunchAgents quebrar o login automático. Veja login automático em um Mac sem monitor.

6. Uma etapa de pipeline para o Mac

steps:
  - label: ":xcode: iOS tests"
    agents:
      queue: "macos"
    commands:
      - "rm -rf build/TestResults.xcresult"
      - "xcodebuild test -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.5' -resultBundlePath build/TestResults.xcresult"
      - "ditto -c -k --keepParent build/TestResults.xcresult build/TestResults.xcresult.zip"
    artifact_paths:
      - "build/TestResults.xcresult.zip"
    timeout_in_minutes: 30
    retry:
      automatic:
        - exit_status: -1
          limit: 2

A nova tentativa com exit_status: -1 vem do exemplo de command step do Buildkite. Ela repete um job quando o próprio agente se perdeu, não quando um teste falhou.

Erros comuns e soluções

• O launchctl diz Could not find domain for. O Buildkite diz que um usuário precisa estar logado no Mac. Entre na área de trabalho e carregue o serviço de novo.
• Refusing to load formula ... from untrusted tap. Rode brew trust buildkite/buildkite e instale de novo.
• O agente não conecta. O token está errado, ou a chave da fila em tags não existe neste cluster.
• O agente não consegue clonar. Coloque a chave em ~/.ssh do usuário que roda o agente.
• xcodebuild: error: Existing file at -resultBundlePath. Os builds reaproveitam o checkout. Apague o bundle antes, como acima.

Para atualizar depois, rode brew update && brew upgrade buildkite/buildkite/buildkite-agent@3.

Por que um Mac dedicado ajuda

O Buildkite foi feito para as suas próprias máquinas, e um Mac permanente mantém os caches. No nosso benchmark com o app iOS da Wikipedia no Xcode 26.6, um job depois de uma pequena mudança levou 27 segundos em um M6 aquecido. Um runner macos-26 novo hospedado pelo GitHub levou 269 segundos.

Quando os agentes hospedados do Buildkite bastam

O Buildkite também oferece agentes macOS hospedados. Você escolhe esses agentes ao criar uma fila hospedada, segundo a documentação lida em outubro de 2026. Se você não quer cuidar de nenhuma máquina, esse é o caminho mais simples. A MacRun também não é a escolha certa se você precisa de um SLA, de um IP fixo para regras de token ou de mais de uma região.

Para o lado da MacRun, veja outros sistemas de CI. Para o que rodar nas etapas, veja o guia de pipeline de CI/CD para iOS.