Rodando seu próprio Forgejo Runner no Codeberg: guia prático de CI/CD self-hosted

Por que ter seu próprio runner de CI/CD?

Se você anda testando o Codeberg como alternativa ao GitHub, já deve ter percebido que ele é uma excelente opção. Desenvolvido sobre o Forgejo e mantido por uma organização sem fins lucrativos, o Codeberg oferece uma plataforma mais privada e comunitária para controle de versão. Porém, como qualquer projeto sem fins lucrativos, a infraestrutura de runners compartilhados tem limitações.

A solução está em hospedar seu próprio runner do Forgejo. O melhor é que esses runners fazem conexões de saída para o Codeberg, o que significa que eles funcionam perfeitamente em um VPS, servidor em casa ou até em um notebook. Sem necessidade de abrir portas.

Como funciona a arquitetura

Antes de configurar, é importante entender o que estamos montando. Um runner do Forgejo funciona como um trabalhador que recebe jobs do Codeberg e os executa. Por segurança, vamos isolá-lo do sistema principal usando Docker-in-Docker (DinD). Isso permite que o runner crie ambientes em containers sem precisar tocar no Docker do host — um detalhe importante para manter tudo seguro.

Montando o Docker Compose

O núcleo da configuração é um sistema simples com dois containers:

version: '3.8'

services:
  docker-in-docker:
    image: docker:dind
    container_name: 'docker_dind'
    privileged: 'true'
    command: ['dockerd', '-H', 'tcp://0.0.0.0:2375', '--tls=false']
    restart: 'unless-stopped'

  runner:
    image: 'data.forgejo.org/forgejo/runner:12'
    links:
      - docker-in-docker
    depends_on:
      docker-in-docker:
        condition: service_started
    container_name: 'runner'
    environment:
      DOCKER_HOST: tcp://docker-in-docker:2375
    user: 1001:1001
    volumes:
      - ./data:/data
    restart: 'unless-stopped'
    command: 'forgejo-runner daemon --config runner-config.yml'

Aqui criamos dois containers: um fornece um ambiente Docker isolado,而另一个 é o runner que se comunica com ele.

Preparando o sistema

Antes de iniciar os containers, você precisa organizar a estrutura de diretórios com as permissões corretas. Recomendamos criar tudo em /opt/forgejo-runner e executar:

cd /opt/forgejo-runner
mkdir -p data/.cache
chown -R 1001:1001 data
chmod 775 data/.cache
chmod g+s data/.cache

Next, generate the default configuration file:

sudo sh -c 'docker run --rm data.forgejo.org/forgejo/runner:12 forgejo-runner generate-config > data/runner-config.yml'

Isso cria um arquivo de configuração bem documentado que você pode customizing.

Registrando seu runner no Codeberg

Agora é hora, a integração. Acesse as configurações da sua conta (ou organização) no Codeberg e vá em Actions → Runners. Clique em "Create new runner", escolha um nome fácil de lembrar e, se quiser, adicione uma descrição.

Codeberg vai gerar um UUID e um Token — anote-os imediatamente. Esses valores permitem que seu runner se autentique com o Codeberg. Você não verá esses valores novamente sem um reset.

Os Codeberg mostra exatamente o snippet de YAML que você precisa, para que não tenha de escrever por conta de نفس.