Como configurei GitLab Runners em uma aplicação self-hosted

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.

Apr 23, 2025 - 17:53

Como configurei GitLab Runners em uma aplicação self-hosted

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.