GitHub Actions na VPS: Runner Próprio para CI/CD

Você sente que o custo e a latência dos runners compartilhados do GitHub estão comprometendo seus pipelines de integração contínua? Ao configurar um runner próprio em sua VPS, você recupera o controle total sobre o ambiente, reduz drasticamente os custos de execução e acelera o tempo de build com hardware dedicado ao seu projeto.

Pré-requisitos

Antes de iniciar a configuração do github actions em sua infraestrutura, é fundamental garantir que o ambiente esteja preparado para receber e executar os agentes de build. A falta de qualquer um destes itens pode resultar em falhas silenciosas ou timeouts durante a execução dos jobs.

• Uma VPS ou Servidor Dedicado com Linux: Recomendamos Ubuntu 20.04/22.04 LTS, Debian 11/12 ou Amazon Linux 2. O sistema deve ter privilégios de root ou acesso via sudo.
• Acesso SSH Seguro: Conexão estável com chave SSH configurada para evitar autenticação por senha repetitiva.
• Conta GitHub com Permissões de Admin: Você precisa ser proprietário ou administrador do repositório onde o runner será registrado. Permissões de "Write" são insuficientes para registrar novos runners.
• Recursos Mínimos do Sistema: Pelo menos 2 vCPUs e 4GB de RAM para runners genéricos. Se estiver compilando grandes projetos (Java, C++, Go), considere 4 vCPUs e 8GB+ de RAM para evitar OOM Killer (Out of Memory).
• Firewall Aberto: A porta 22 (SSH) deve estar acessível. Para comunicação com o GitHub, as portas 443 (HTTPS/TLS) e 80 (HTTP, se usar HTTP proxy) devem estar abertas para tráfego de saída.

Verifique a conectividade de saída com seu provedor de nuvem. Alguns ambientes restritivos podem bloquear conexões diretas ao GitHub, exigindo configuração de proxy ou túneis.

Passo a passo: Instalação e Configuração

A instalação de um runner autogerenciado (self-hosted) envolve baixar o pacote oficial, extraí-lo em um diretório não-root para segurança e registrá-lo no repositório. Vamos dividir este processo em etapas lógicas para garantir uma implementação limpa e reproduzível.

1. Preparação do Ambiente

Comece atualizando o sistema operacional e instalando dependências básicas necessárias para a maioria dos builds, como curl, git e unzip.

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git unzip tar jq

Crie um usuário dedicado para executar o runner. Nunca execute o runner como root, pois isso expõe seu servidor a riscos de segurança graves caso haja vulnerabilidades no código compilado ou nos scripts de build.

sudo useradd -m -s /bin/bash runner
sudo mkdir -p /home/runner/actions-runner
sudo chown -R runner:runner /home/runner/actions-runner

2. Download do Pacote do Runner

Visite a página de releases do GitHub Actions Runners no GitHub para verificar a versão mais recente. No momento desta escrita, utilizaremos a versão estável mais recente. O script abaixo baixa e extrai o runner no diretório criado.

SUITE="ubuntu-22.04"
RUNNER_VERSION="2.316.0" # Verifique a versão mais recente no GitHub

cd /home/runner/actions-runner
sudo curl -o actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz -L https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz
sudo tar xzf ./actions-runner-linux-x64-${RUNNER_VERSION}.tar.gz

Se você estiver em uma arquitetura ARM (como Raspberry Pi ou AWS Graviton), substitua o URL pelo link correspondente a linux-arm64.

3. Configuração e Registro no Repositório

Agora, precisamos gerar o token de registro. Vá ao seu repositório no GitHub em Settings > Actions > Runners e clique em New self-hosted runner. Copie o comando de configuração exibido na tela. Ele conterá um token JWT de curta duração.

Execute o script config.sh como o usuário runner. O comando abaixo é um exemplo genérico; substitua os valores conforme necessário.

cd /home/runner/actions-runner
sudo -u runner ./config.sh --url https://github.com/SEU-USUARIO-OU-ORG/SEU-REPOSITORIO --token SEU_TOKEN_DE_REGISTRO_AQUI

O script solicitará configurações adicionais:

• Runner Name: Um nome descritivo, ex: vps-ci-01.
• Groups: Pressione Enter para usar o padrão.
• Work Folder: Pressione Enter para usar _work.

Após a execução bem-sucedida, o script criará um arquivo .runner no diretório atual. Esse arquivo contém as credenciais de comunicação com o GitHub.

4. Execução como Serviço Systemd

Para garantir que o runner inicie automaticamente após reinicialções e seja gerenciado corretamente, crie um serviço systemd.

sudo nano /etc/systemd/system/actions-runner.service

Cole a seguinte configuração, ajustando o caminho do usuário e diretório se necessário:

[Unit]
Description=GitHub Actions Runner
After=network.target

[Service]
Type=simple
User=runner
Group=runner
WorkingDirectory=/home/runner/actions-runner
ExecStart=/home/runner/actions-runner/run.sh
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Habilite e inicie o serviço:

sudo systemctl daemon-reload
sudo systemctl enable actions-runner.service
sudo systemctl start actions-runner.service

Verifique o status para garantir que não há erros críticos:

sudo systemctl status actions-runner.service

Verificação e Teste

Com o serviço em execução, o próximo passo é validar se a comunicação bidirecional está funcionando. O GitHub deve reconhecer seu runner como "Online" e pronto para receber jobs.

Acesse novamente a página Settings > Actions > Runners no seu repositório. Você deverá ver o nome do seu runner listado com um status verde. Se aparecer um ícone de alerta ou cinza, clique nele para ver os logs de erro detalhados.

Para um teste funcional, crie um arquivo .github/workflows/test.yml no seu repositório:

name: Test Runner
on: [push]

jobs:
  test:
    runs-on: self-hosted
    steps:
      - name: Check environment
        run: |
          echo "Hostname: $(hostname)"
          echo "User: $(whoami)"
          echo "Git Version: $(git --version)"
          df -h

Faça um commit e push para a branch principal. Acompanhe o pipeline no aba Actions. Se o job for atribuído ao seu runner e passar com sucesso, sua configuração está completa.

Dica Pro: Use labels para segmentar cargas de trabalho. No arquivo de configuração do runner ou via variáveis de ambiente, você pode definir labels específicas (ex: docker, high-memory) e no workflow usar runs-on: [self-hosted, docker].

Troubleshooting: Problemas Comuns

Embora a instalação seja direta, ambientes de produção enfrentam desafios únicos. Abaixo estão os cenários mais frequentes e suas resoluções.

Runner não aparece na lista do GitHub

Se o serviço está rodando localmente mas o GitHub não mostra o runner:

1. Verifique a Conectividade de Saída: O servidor precisa acessar api.github.com e github.com. Teste com curl -I https://api.github.com.
2. Confira o Tempo do Sistema: Desvio grande na hora do servidor invalida os tokens JWT. Execute sudo timedatectl set-ntp true para sincronizar com NTP.
3. Logs do Systemd: Execute journalctl -u actions-runner.service -f para ver erros em tempo real.

Jobs falham com erro de permissão (Permission Denied)

Ocorrerá se o usuário runner não tiver acesso a arquivos necessários ou tentar escrever em pastas protegidas.

Atenção: Evite usar sudo dentro dos seus scripts de CI/CD. Configure permissões adequadas nos diretórios do projeto antes do build.

Solução: Verifique se o diretório de trabalho _work está acessível e se as chaves SSH ou tokens de deploy estão exportados corretamente nas variáveis do repositório, não no código.

Runner "Offline" após reinicialização

Isso geralmente indica que o serviço systemd não foi habilitado corretamente ou falhou ao iniciar.

1. Verifique se o serviço está habilitado: systemctl is-enabled actions-runner.service.
2. Se falhar, verifique os logs: journalctl -u actions-runner.service --no-pager -n 50.
3. Certifique-se de que o diretório /home/runner/actions-runner não foi removido ou teve permissões alteradas.

Consumo excessivo de CPU/Memória

Runners autogerenciados podem consumir muitos recursos se não forem limitados. Se seu servidor hospeda outros serviços, isso pode causar instabilidade.

Solução: Utilize cgroups via systemd para limitar recursos. Edite o arquivo de serviço:

[Service]
...
MemoryMax=2G
CPUQuota=150%

Recarregue e reinicie: sudo systemctl daemon-reload && sudo systemctl restart actions-runner.service.

Perguntas frequentes

Posso usar o mesmo runner para múltiplos repositórios?

Sim. Ao registrar o runner, você pode adicioná-lo a vários repositórios da mesma organização ou conta pessoal. No entanto, considere separar runners por tipo de carga (ex: um para Node.js, outro para .NET) para evitar conflitos de dependências e otimizar o uso de cache.

Como atualizo a versão do runner?

Baixe a nova versão, pare o serviço, substitua os arquivos binários e reinicie. O arquivo .runner deve ser preservado para manter as configurações existentes.

sudo systemctl stop actions-runner.service
# Backup do config atual
cp .runner .runner.bak
# Download nova versão e extração
# Substitua os arquivos antigos
sudo systemctl start actions-runner.service

É seguro manter um runner na minha VPS?

Sim, se seguir boas práticas. Nunca execute como root. Use usuários dedicados, mantenha o sistema atualizado e limite as permissões de leitura/escrita no sistema de arquivos. Runners autogerenciados não executam código malicioso por padrão, mas um pipeline comprometido pode tentar acessar recursos locais.

Como lidar com builds paralelos?

Por padrão, um runner executa um job por vez. Para parallelismo, você precisa de múltiplas instâncias do runner. Crie usuários separados (ex: runner2, runner3) e serviços systemd distintos apontando para o mesmo token ou tokens individuais.

Posso usar Docker dentro do meu runner?

Sim. Instale o Docker Engine no servidor e adicione o usuário runner ao grupo docker: sudo usermod -aG docker runner. Seus workflows poderão usar runs-on: self-hosted e chamar comandos docker build/push diretamente.

Conclusão

Configurar um runner próprio em sua VPS é um passo fundamental para amadurecer sua estratégia de DevOps. Você ganha flexibilidade para instalar ferramentas específicas, reduz custos operacionais a longo prazo e mantém seus dados sensíveis dentro da sua infraestrutura controlada. A implementação técnica, embora exija atenção aos detalhes de permissões e serviços, é robusta e bem documentada pela comunidade.

A automação eficiente não depende apenas de ferramentas poderosas, mas também da estabilidade da infraestrutura que as sustenta. Um runner configurado corretamente assegura que seus builds sejam rápidos, seguros e previsíveis.

Se você ainda não possui a infraestrutura ideal para suportar seus pipelines de alta performance, experimente hospedagem cloud na Toda Solução. Nossos servidores são otimizados para cargas de trabalho de desenvolvimento, oferecendo baixa latência e alto desempenho para seus projetos.