Como configurar e instalar um Runner Docker no Gitlab

Já estourou sua cota de minutos de execução na CICD do gitlab? Ou usa o Gitlab self hosted? Então esse artigo é para você, nele vamos mostrar como instalar e configurar um runner Docker e suas principais configurações, lembrando que tudo que for mostrado aqui vai servir para quem usa SAAS ou self hosted em todas as versões de licença (gratuito, premium e ultimate).

O Runner Docker do gitlab acaba por se tornar uma opção bem flexível para quem deseja construir vários projetos e deseja um ambiente homogêneo, isso porque, você só precisa ter na máquina o docker e nenhuma outra dependência adicional, além disso ele nos permite construir nossas imagens de container. Porém caso este modelo não seja compatível com suas necessidades, o gitlab também disponibiliza outros tipos Comparando todos os tipos de Runners do Gitlab basta ler nosso artigo e adaptar esse para suas necessidades. Para este tutorial vamos usar o Linux como sistema operacional, porém as configurações do agente tendem a não mudar, só muda a forma de instalação.

Pré-Requisitos

• Docker
• Conta ou gitlab instalado

Gerando token de conexão do Runner

Ao escolher o nível em que deseja inserir o runner (projeto, grupo ou instância) você poderá navegar até o menu lateral Build -> Runners e preencher algumas informações, por exemplo se seu runner vai rodar qualquer tipo de job ou apenas os jobs com runners, o Sistema Operacional dele (Linux, MacOs ou Windows), a descrição e o tempo limite de execução (timeout) de cada job. Para nosso exemplo chegamos a esse resultado:

Após preencher essas informações você receberá um token de instalação, guarde ele pois usaremos mais a frente.

Instalar o Runner docker do gitlab localmente

Runner como serviço

Em uma máquina com Docker previamente instalado vamos rodar os seguintes comandos para instalação e configuração do runner, vale lembrar, que a instalação do runner mesmo não precisa do docker porém como vamos rodar jobs do tipo docker ele vai precisar dele configurado.

sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

sudo chmod +x /usr/local/bin/gitlab-runner

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

Agora vamos usar o comando que criamos na página anterior para registrar o runner, no nosso exemplo ficou assim:

gitlab-runner register  --url https://gitlab.com  --token glrt-Ssg1Hye3sg2Qpft1

Este comando vai rodar em modo interativo e vamos escolher os seguintes fluxos:

• Instância URL do gitlab = URL onde o seu gitlab está instalado, no nosso caso https://gitlab.com/
• Nome do Runner = nome que será exibido na página de runners, no nosso caso runner-wsl
• Tipo de Executor = aqui vamos definir o modo de trabalho e queremos que ele seja do tipo docker
• Imagem Padrão = essa é a imagem que o runner já terá feito pull, coloque aqui a imagem que costuma usar com mais frequência

No nosso exemplo final teremos esse cenário:

Após a configuração você pode configurar o runner para iniciar sempre com o sistema operacional, ou validar a configuração desta forma:

sudo systemctl enable gitlab-runner # inicia junto com o sistema operacional
sudo systemctl status gitlab-runner # valida status do serviço
gitlab-runner verify # valida configuração do config.toml

Runner como container

Se não quiser instalar nada além do docker na sua máquina, existe esse docker compose criado pela comunidade e atualizado por nós que faz a mesma coisa do comando anterior porém só usando docker, esse projeto pode ser encontrado na versão original em: Gitlab

version: "3.5"

services:
  dind:
    image: docker:26.0.2-dind
    restart: always
    privileged: true
    environment:
      DOCKER_TLS_CERTDIR: ""
    command:
      - --storage-driver=overlay2

  runner:
    restart: always
    image: registry.gitlab.com/gitlab-org/gitlab-runner:alpine
    depends_on:
      - dind
    environment:
      - DOCKER_HOST=tcp://dind:2375
    volumes:
      - ./config:/etc/gitlab-runner:z

  register-runner:
    restart: 'no'
    image: registry.gitlab.com/gitlab-org/gitlab-runner:alpine
    depends_on:
      - dind
    environment:
      - CI_SERVER_URL=${CI_SERVER_URL}
      - REGISTRATION_TOKEN=${REGISTRATION_TOKEN}
    command:
      - register
      - --non-interactive
      - --locked=false
      - --name=${RUNNER_NAME}
      - --executor=docker
      - --docker-image=docker:26.0.2-dind
      - --docker-volumes=/var/run/docker.sock:/var/run/docker.sock
    volumes:
      - ./config:/etc/gitlab-runner:z

Validando Runners no gitlab

No final da configuração teremos na nossa página de runners o runner cadastrado e se tudo estiver certo ele está com o status de “active” conforme pode ser visto na imagem abaixo:

Conclusão

Já temos nosso runner configurado e rodando, o que achou dessa configuração? Lembrando que podemos fazer configurações adicionais, por exemplo indicar o local de armazenamento do cache (S3, GCS e Azure), mapeamento de volumes, política de gerenciamento de recursos entre outras configurações. Para ver essa parte mais avançada na configuração de um runner, deixe seu comentário, para que possamos saber e se achou algum erro durante a execução do tutorial comente também para que possamos atualizar o artigo.