Em um ambiente self-hosted, precisei configurar um runner para executar pipelines de CI/CD diretamente em uma VM Linux usando o executor shell. Abaixo explico como fiz isso do zero.

Pré-requisitos

Antes de tudo, eu já tinha:

  • Acesso root (ou sudo) à VM Linux
  • Um GitLab self-hosted configurado
  • Privilégios como mantenedor em um repositório no GitLab

Habilitar CI/CD no repositório

Como sou mantenedor dos repositórios, consigo criar runners por projeto, o que acaba que o runner fica especificamente acessível aquele projeto apenas, não sendo de escopo de instância ou grupo (quando o runner pode ser compartilhado com outros projetos/repositórios), nas configurações do repositório, fui em:

Configurações → Geral → Visibilidade, recursos do projeto, permissões

Expandi a seção e habilitei o CI/CD

Instalando o GitLab Runner

Na VM, como sou administrador, consigo então instalar os pacotes necessários, complementares a aplicação self-hosted do GitLab, preferi instalar o runner, os comandos/instruções são fornecidas no próprio painel do GitLab ou encontradas aqui na própria documentação do GitLab.

# Download the binary for your system
sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
# Give it permission to execute
sudo chmod +x /usr/local/bin/gitlab-runner

Depois criei o usuário e configurei o runner como serviço:

sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

Registrando o runner no projeto

Como mantenedor do repositório, fui em:

Configurações → CI/CD → Runners → Novo executor de projeto

Escolhi a plataforma Linux, criei uma tag e marquei a opção “Executar jobs sem tags”.

Depois, no terminal da minha VM, executei:

gitlab-runner register \
  --url https://example.com.br \
  --token SEU_TOKEN

Durante o processo, selecionei o executor do tipo shell.

Verificando se o runner foi configurado

Rodei o comando:

gitlab-runner list

E depois executei:

gitlab-runner run

O runner foi registrado no arquivo:

/home/user/.gitlab-runner/config.toml

No GitLab, consegui visualizá-lo em Configurações → CI/CD → Runners.

Criando pipeline de teste

No repositório, criei o arquivo .gitlab-ci.yml com:

stages:
  - test

runner_test:
  stage: test
  script:
    - echo "Runner funcionando!"
    - uname -a

E subi para o GitLab:

git add .gitlab-ci.yml
git commit -m "teste do runner"
git push origin main

Depois fui em:

CI/CD → Pipelines

O job foi executado com sucesso, usando o runner shell que registrei.

Remover runner (se necessário)

Para remover um runner, editei o arquivo config.toml:

sudo vim /home/user/.gitlab-runner/config.toml

Apaguei o bloco referente ao runner e depois reiniciei:

sudo gitlab-runner restart
gitlab-runner list

Conclusão

Essa abordagem com executor shell é útil para ambientes simples ou controlados.