Análise do problema

No processo de integração e entrega contínuas (CI/CD), o GitLab Runner é responsável por executar os trabalhos definidos nos pipelines. Quando um runner apresenta falhas, como timeouts ou estado offline, isso pode interromper todo o fluxo de desenvolvimento. Um erro comum é a mensagem "Runner is not healthy and will be disabled", acompanhada de falhas de timeout durante a execução dos jobs.

Ao verificar o status do serviço no servidor onde o runner está instalado, mesmo que o processo esteja ativo, erros internos podem impedir sua comunicação com o servidor GitLab. O primeiro passo é confirmar o estado do serviço:

systemctl status gitlab-runner -l

O resultado pode indicar que o serviço está em execução, mas com mensagens de erro relacionadas à autenticação ou conectividade.

Verificação do arquivo de configuração

O arquivo /etc/gitlab-runner/config.toml armazena informações críticas sobre o runner, incluindo o token de registro. Se esse token estiver desatualizado ou incorreto, o runner não conseguirá se autenticar no projeto GitLab. Para verificar:

cat /etc/gitlab-runner/config.toml

Compare o valor do campo token com o token atual exibido na interface web do GitLab, localizado em Projeto → Configurações → CI/CD → Runners específicos. A discrepância entre esses valores é uma causa comum de falha de comunicação.

Registro novamente do GitLab Runner

Para corrigir o problema, o runner deve ser reconfigurado com um token válido. Siga os passos abaixo:

1. Parar o serviço do runner

sudo systemctl stop gitlab-runner

2. Remover o runner antigo (opcional)

Se necessário, remova o runner registrado anteriormente para evitar conflitos:

sudo gitlab-runner unregister -n gitlab-runner

3. Regsitrar um novo runner

Execute o comando de registro e siga as instruções:

sudo gitlab-runner register

• URL do GitLab: Informe a URL do seu servidor GitLab (ex: https://gitlab.com)
• Token do runner: Copie o token atual da seção de runners específicos no projeto
• Descrição: Nome identificável (ex: runner-producao-linux)
• Tags: Defina tags relevantes para o tipo de job que ele executará (ex: build, test, deploy)
• Anotação de manutenção (opcional): Pode ser deixada em branco
• Executor: Escolha o executor adequado ao ambiente. Para ambientes simples, use shell. Em cenários mais isolados, considere docker.

4. Reiniciar o serviço

Após o registro bem-sucedido, inicie o serviço novamente:

sudo systemctl start gitlab-runner

Garanta que ele inicie automaticamente após reinicializações:

sudo systemctl enable gitlab-runner

Validação da correção

Após a reocnfiguração, verifique:

• O status do serviço: systemctl status gitlab-runner
• O estado do runner na interface do GitLab — ele deve aparecer como "online"
• Execute um pipeline de teste para confirmar que os jobs são processados sem timeouts

Conclusão

A falha de saúde em um GitLab Runner geralmente está ligada a problemas de configuração, especialmente com o token de autenticação. Recriar o registro do runner com credenciais atualizadas restaura a comunicação com o servidor GitLab e resolve erros de timeout e indisponibilidade. Manter os runners monitorados e suas configurações sincronizadas é essencial para a confiabilidade dos pipelines CI/CD.