Como configurar um runner auto-hospedado do GitHub Actions num VPS

Registre um runner auto-hospedado do GitHub Actions num VPS e instale-o como serviço: baixe o runner como usuário não-root, registre com o token do repo, execute o svc.sh para que sobreviva a reinícios. Comandos copiar-colar.

Um runner auto-hospedado te dá CI de custo fixo com caches quentes — sem cobrança por minuto, sua toolchain, sua máquina. Este é o guia de configuração mínimo; para saber por que a auto-hospedagem ganha dos minutos hospedados pelo GitHub e os detalhes de jobs Docker, veja o guia completo e o caso de uso VPS para GitHub Actions.

1. Crie um usuário não-root (o runner recusa root)

adduser --disabled-password --gecos "" runner
su - runner

2. Baixe o runner

No GitHub: Settings → Actions → Runners → New self-hosted runner → Linux, o que te dá o download exato e um token de uso único. Depois:

mkdir actions-runner && cd actions-runner
curl -o actions-runner-linux-x64.tar.gz -L \
  https://github.com/actions/runner/releases/latest/download/actions-runner-linux-x64.tar.gz
tar xzf actions-runner-linux-x64.tar.gz

3. Registre-o com seu repo

./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO --token YOUR_TOKEN

4. Instale como serviço (sobrevive a reinícios)

Não execute ./run.sh num terminal — instale-o:

sudo ./svc.sh install runner
sudo ./svc.sh start
sudo ./svc.sh status

O runner agora aparece como Idle na interface do GitHub e pega os jobs que o têm como alvo.

5. Use-o a partir de um workflow

jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - run: make build && make test

Jobs Docker (opcional)

Instale o Docker uma vez, e os workflows podem construir imagens com o cache de camadas persistindo entre execuções:

sudo apt install -y docker.io
sudo usermod -aG docker runner

Veja instalar Docker num VPS. Dimensionamento: Small (US$ 8/mês) é confortável para a maioria do CI; suba de nível para compilação pesada. Root em cerca de um minuto, sem KYC, pagamento em cripto.

Perguntas frequentes

Como registro um runner auto-hospedado do GitHub Actions?

No seu repo (ou org): Settings → Actions → Runners → New self-hosted runner → Linux. O GitHub mostra um comando de download e um token de registro de uso único. Baixe o runner como usuário não-root, execute ./config.sh com essa URL e o token, depois instale-o como serviço com svc.sh. Os passos estão abaixo.

Por que o runner não pode rodar como root?

O runner se recusa a rodar como root por design. Crie um usuário não-root dedicado (adduser runner) e configure-o lá. Isso também limita o que um workflow malicioso poderia tocar na sua máquina.

Como mantenho o runner rodando após reiniciar?

Use o auxiliar svc.sh incluído: sudo ./svc.sh install runner && sudo ./svc.sh start. Ele instala uma unidade systemd para o runner iniciar no boot e reiniciar em falhas, e aparecer como Idle na interface do GitHub.

Preciso de um IP dedicado para um runner?

Não. O runner disca para fora até o GitHub por HTTPS; nada precisa alcançá-lo de entrada. Um plano NAT (a partir de US$ 3/mês) serve. Só pegue um IP dedicado se também auto-hospedar algo que serve tráfego.

Vocês pedem documento ou cartão?

Não. Um e-mail para cadastrar, pagamento em USDC ou USDT — sem documentos, sem cartão. Root em cerca de um minuto.

Comentários

Nenhum comentário ainda. Seja o primeiro.