Forgejo + Woodpecker CI: Alternativa Self-Hosted ao GitHub para PME

Introdução — Forgejo vs GitHub

O GitHub dominou o mercado de hospedagem Git, mas para PME portuguesas a dependência de um serviço cloud norte-americano levanta questões de custo, privacidade e soberania de dados. O Forgejo (fork do Gitea, mantido pela Codeberg e.V.) combinado com o Woodpecker CI oferece uma alternativa self-hosted, open-source e gratuita.

Funcionalidade GitHub (cloud) Forgejo + Woodpecker
Custo Grátis até limites; 4 USD/util/mês Gratuito (só custo do servidor)
Repositórios privados Ilimitados em planos pagos Ilimitados sem restrições
CI/CD GitHub Actions (2000 min grátis/mês) Woodpecker CI ilimitado
Localização dados EUA / UE Teu servidor (RGPD)
Soberania Proprietário (Microsoft) Open-source (MIT)

ℹ Quando escolher esta stack

PME com 5 a 50 programadores, repositórios privados ilimitados, controlo total de dados (RGPD) e um servidor/VPS com 2 GB de RAM. O custo total é uma fracção do GitHub Teams.

Instalar Forgejo com Docker

A forma mais simples de instalar o Forgejo é via Docker Compose com PostgreSQL. Cria o ficheiro docker-compose.yml:

services:
  forgejo-db:
    image: postgres:16-alpine
    restart: always
    environment:
      POSTGRES_USER: forgejo
      POSTGRES_PASSWORD: troca-esta-pass
      POSTGRES_DB: forgejo
    volumes: [./postgres-data:/var/lib/postgresql/data]

  forgejo:
    image: codeberg.org/forgejo/forgejo:7
    restart: always
    depends_on: [forgejo-db]
    environment:
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=forgejo-db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=troca-esta-pass
    ports: ["3000:3000", "2222:22"]
    volumes: [./forgejo-data:/data]

Arranca com docker compose up -d e acede a http://servidor:3000 para criar a conta de administrador. O porto SSH para clonar repositórios é o 2222.

⚠ Segurança do porto SSH

Não abras o porto 2222 directamente à Internet sem firewall. Usa um reverse proxy e desabilita login por palavra-passe no SSH do servidor.

Configurar Woodpecker CI

Cria uma aplicação OAuth no Forgejo: Settings > Applications > OAuth2 com Redirect URI https://ci.teudominio.pt/authorize. Depois adiciona ao docker-compose.yml:

  woodpecker-server:
    image: woodpeckerci/woodpecker-server:v2.7
    restart: always
    environment:
      - WOODPECKER_HOST=https://ci.teudominio.pt
      - WOODPECKER_FORGEJO=true
      - WOODPECKER_FORGEJO_URL=http://forgejo:3000
      - WOODPECKER_FORGEJO_CLIENT=CLIENT_ID
      - WOODPECKER_FORGEJO_SECRET=CLIENT_SECRET
      - WOODPECKER_AGENT_SECRET=secret-longo
    ports: ["8000:8000", "9000:9000"]
    volumes: [./woodpecker-data:/var/lib/woodpecker]

  woodpecker-agent:
    image: woodpeckerci/woodpecker-agent:v2.7
    restart: always
    depends_on: [woodpecker-server]
    environment:
      - WOODPECKER_SERVER=woodpecker-server:9000
      - WOODPECKER_AGENT_SECRET=secret-longo
      - WOODPECKER_BACKEND=docker
    volumes: [/var/run/docker.sock:/var/run/docker.sock]

Reinicia com docker compose up -d e autentica-te em https://ci.teudominio.pt com a conta Forgejo. O Woodpecker lista os repositórios — activa um com Activate. Precisa de HTTPS para webhooks; o Caddy é o reverse proxy mais simples (certificado Let’s Encrypt automático).

Pipelines e Runners

Os pipelines definem-se num ficheiro .woodpecker.yml na raiz do repositório. Exemplo para Node.js:

when:
  - event: push
    branch: main

steps:
  - name: install
    image: node:20-alpine
    commands: [npm ci]
  - name: test
    image: node:20-alpine
    commands: [npm test]
  - name: build
    image: node:20-alpine
    commands: [npm run build]

Os runners executam os pipelines. O Woodpecker suporta backends Docker (contentores isolados), Local (host directo), Kubernetes (pods efémeros) e SSH (servidor remoto). Para escalar, adiciona mais agentes com o mesmo WOODPECKER_AGENT_SECRET — o load balancing é automático. Usa o plugin woodpeckerci/plugin-cache para fazer cache de dependências e reduzir o tempo de pipeline em 60-80%.

Erros Comuns

Erro Causa Solução
Webhook não dispara Woodpecker não chega ao Forgejo Verificar FORGEJO_URL com endereço interno
Erro 401 OAuth Redirect URI incorrecta URI exacta: https://ci.teudominio.pt/authorize
Pipeline em pending Agente sem acesso Docker Confirmar mount de /var/run/docker.sock e permissões
Clone falha no pipeline Agente não acede ao Forgejo URL acessível pelo agente ou skip_verify: true
Push SSH rejeitado Firewall bloqueia 2222 Abrir porto 2222 ou mapear para 22
Permission denied Docker Agente sem acesso ao socket Adicionar agente ao grupo docker

A stack Forgejo + Woodpecker CI é uma alternativa madura ao GitHub para PME que valorizam soberania de dados, custo controlado e flexibilidade. Com Docker Compose, a instalação leva menos de 30 minutos.

Artigos relacionados no kbase.pt