Como instalar o GitLab CI em um VPS

Pré-requisitos

Prepare um VPS Ubuntu 22.04 ou 24.04 dedicado, com SSH, Docker e pelo menos 2 GB de RAM. Tarefas de compilação pesadas precisam de mais CPU, memória e espaço em disco. Você também precisa de um projeto ou grupo do GitLab no qual tenha permissão para criar um runner, além de uma política para solicitações de mesclagem não confiáveis.

Um runner executa código das tarefas de CI. Trate-o como uma infraestrutura descartável, mantenha credenciais de produção longe de pipelines não confiáveis e não compartilhe um runner privilegiado entre equipes sem relação entre si.

O que este guia instala: Este guia instala SOMENTE o agente GitLab Runner, o serviço leve que executa tarefas de CI/CD. É necessária uma instância EXISTENTE do GitLab (gitlab.com ou auto-hospedada) para registrá-lo. Este guia NÃO instala o servidor GitLab completo.

Etapa 1, Conectar ao servidor

Atualize a máquina e crie um diretório para o runner:

ssh root@SERVER_IP
apt update && apt upgrade -y
apt install -y ca-certificates curl
mkdir -p /opt/gitlab-runner/config
cd /opt/gitlab-runner
chmod 750 /opt/gitlab-runner

Permita apenas SSH, a menos que o servidor execute outro serviço. Em geral, um runner não precisa de HTTP nem HTTPS públicos. Restrinja o acesso de saída à rede se suas tarefas não precisarem de acesso irrestrito à internet.

Etapa 2, Instalar o Docker e o Docker Compose

Instale o Docker Engine e o plugin Compose seguindo as instruções oficiais do Docker para Ubuntu:

docker --version
docker compose version
systemctl enable --now docker

O executor Docker precisa acessar o Docker. Esse acesso é poderoso, portanto use um VPS dedicado e não monte diretórios não relacionados do servidor nas tarefas.

Aviso: Montar /var/run/docker.sock dá ao contêiner do runner acesso ao servidor equivalente ao de root. Qualquer tarefa de CI pode escapar para o servidor. Use esta configuração somente em projetos confiáveis.

Etapa 3, Executar o GitLab Runner com Docker Compose

Crie compose.yaml:

services:
  runner:
    image: gitlab/gitlab-runner:alpine
    restart: unless-stopped
    volumes:
      - ./config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock

Inicie o runner:

docker compose config
docker compose pull
docker compose up -d
docker compose ps

Registre-o a partir do contêiner do runner:

docker compose exec runner gitlab-runner register

Você precisará de um token de registro do projeto GitLab, em Configurações > CI/CD > Runners. As solicitações pedirão:

• A URL da instância do GitLab (por exemplo, https://gitlab.com)
• O token de registro
• Uma descrição e etiquetas para o runner
• O executor: escolha Docker
• A imagem padrão: informe alpine:latest

Informe o token interativamente, nunca em um comando ou artigo que será versionado.

Etapa 4, Não é necessário configurar um proxy reverso

O GitLab Runner não expõe uma porta HTTP; ele se conecta à instância do GitLab por meio de conexões de saída. Não é necessário configurar um proxy reverso.

No GitLab, defina as etiquetas e o status protegido ou não protegido de acordo com seu modelo de confiança. Não permita que repositórios derivados não confiáveis agendem tarefas em um runner que possa acessar credenciais de implantação.

Etapa 5, Primeira tarefa de CI

Acione um pipeline no GitLab e verifique se o runner o recebe. Crie um arquivo .gitlab-ci.yml mínimo em um projeto de teste:

test:
  image: alpine:latest
  script:
    - echo "runner is working"

Envie o arquivo e acompanhe o pipeline. Confirme que a tarefa seleciona o runner esperado, que o contêiner inicia e que os logs não contêm segredos. Teste uma tarefa com falha e outra cancelada para que os responsáveis saibam como o runner se comporta.

Se compilar imagens Docker, escolha o executor e a abordagem Docker-in-Docker documentados pelo GitLab para seus requisitos de segurança. Evite o modo privilegiado, a menos que a tarefa realmente precise dele.

Segurança: O executor Docker dá às tarefas de CI acesso completo ao serviço Docker. Para runners usados por vários projetos, considere VMs efêmeras ou o executor Docker Autoscaler.

Manutenção

Atualize a imagem do runner depois de ler as notas de versão do GitLab Runner e teste um projeto antes de atualizar runners compartilhados. Faça backup da configuração do runner apenas se precisar recriar sua identidade e altere as credenciais de registro pelo GitLab quando a equipe ou os limites de confiança mudarem.

Monitore o espaço em disco ocupado por imagens antigas de tarefas, a conectividade do runner e as tarefas com falha. Limpe os caches com uma política controlada, não apagando todo o volume de configuração.