Was bauen wir?

Am Ende hat dein Forgejo einen registrierten, aktiven Runner, der Workflows aus dem Verzeichnis .forgejo/workflows/ ausführt. Wir setzen dabei auf Docker-in-Docker (DinD): Der Runner startet jeden CI-Job in einem eigenen, wegwerfbaren Container, sauber isoliert vom Host. Konkret läuft am Ende:

• der Forgejo-Runner (code.forgejo.org/forgejo/runner:13.0.0), der bei Forgejo nach Jobs fragt,
• ein Docker-in-Docker-Sidecar (docker:29-dind), in dem die Jobs isoliert laufen,
• ein Beispiel-Repository mit einem Workflow, der bei jedem Push actions/checkout ausführt und eine kleine Aktion startet.

Forgejo Actions ist weitgehend kompatibel zu GitHub Actions – dieselbe Workflow-Syntax, viele Marketplace-Actions funktionieren unverändert. Du kannst also bestehendes Wissen direkt weiternutzen, nur eben auf deinem eigenen Server. Getestet mit Forgejo 16.0.1 und Runner v13.0.0 auf Debian 13 / Docker 29.

Voraussetzungen

• Ein laufender Forgejo-Server hinter einem Reverse Proxy, erreichbar unter einer öffentlichen HTTPS-Domain (DEINE_DOMAIN). Die öffentliche URL ist wichtig – dazu unten mehr.
• Docker auf demselben Server (der Runner und sein DinD-Sidecar laufen als Container).
• Admin-Zugang zu Forgejo, um den Registrierungstoken zu erzeugen.

Actions ist seit Forgejo 1.21 standardmäßig aktiviert. Falls du es in deiner Forgejo-Compose explizit gesetzt hast (empfohlen), steht dort:

    environment:
      FORGEJO__actions__ENABLED: "true"

CI-Jobs sind ressourcenhungriger als der reine Git-Server – Builds brauchen CPU und RAM. Für den Runner-Betrieb neben Forgejo empfehlen wir daher etwas mehr Reserve; wie viel dein konkretes Setup braucht, schätzt der Server-Rechner.

Schritt für Schritt

Schritt 1: Registrierungstoken holen

Der Runner muss sich einmalig bei Forgejo anmelden. Dafür brauchst du einen Registrierungstoken. Am einfachsten holst du ihn über die Weboberfläche: Melde dich als Administrator an und geh auf Administrator-Einstellungen → Actions → Runner. Dort siehst du alle Runner und oben rechts den Knopf Registrierungstoken anzeigen.

Alternativ per Kommandozeile direkt im Forgejo-Container:

docker exec -u git forgejo forgejo actions generate-runner-token

Das gibt einen langen Token aus – kopiere ihn, du brauchst ihn gleich einmal.

Schritt 2: Die Runner-Compose schreiben

Leg einen eigenen Ordner an und wechsle hinein:

mkdir -p /opt/forgejo-runner && cd /opt/forgejo-runner

Erstelle die compose.yaml:

services:
  docker:
    image: docker:29-dind
    container_name: fjr-docker
    privileged: true
    restart: unless-stopped
    environment:
      DOCKER_TLS_CERTDIR: /certs
    volumes:
      - dind_certs:/certs
      - runner_data:/data

  runner:
    image: code.forgejo.org/forgejo/runner:13.0.0
    container_name: fjr-runner
    restart: unless-stopped
    depends_on: [docker]
    environment:
      DOCKER_HOST: tcp://docker:2376
      DOCKER_CERT_PATH: /certs/client
      DOCKER_TLS_VERIFY: "1"
    volumes:
      - dind_certs:/certs:ro
      - runner_data:/data
    working_dir: /data
    command: forgejo-runner daemon

volumes:
  dind_certs:
  runner_data:

Die wichtigsten Punkte:

• Der DinD-Dienst heißt bewusst docker. Sein automatisch erzeugtes TLS-Zertifikat ist auf genau diesen Namen ausgestellt – heißt der Dienst anders, scheitert der Runner mit „certificate is valid for docker, not …" (siehe „Wenn es nicht funktioniert").
• privileged: true braucht DinD, um seine eigene Docker-Engine zu betreiben. Das ist der Preis der Isolation; halte den Runner-Server entsprechend abgesichert.
• Der Runner spricht den DinD über DOCKER_HOST: tcp://docker:2376 mit TLS an; die Client-Zertifikate teilt er sich über das Volume dind_certs.
• Die Registrierung landet als .runner-Datei im Volume runner_data und übersteht so Neustarts und Updates.

Schritt 3: DinD starten und den Runner registrieren

Starte zuerst nur den DinD-Sidecar, damit er seine Zertifikate erzeugt:

docker compose up -d docker

Jetzt registrierst du den Runner einmalig. Ersetze DEIN_TOKEN durch den Token aus Schritt 1:

docker compose run --rm runner forgejo-runner register \
  --no-interactive \
  --instance https://DEINE_DOMAIN \
  --token DEIN_TOKEN \
  --name mein-runner \
  --labels "docker:docker://node:24-bookworm"

Bei Erfolg endet die Ausgabe mit Runner registered successfully. (eine Warnung, dass register „deprecated" sei, kannst du ignorieren – es funktioniert).

Das Label docker:docker://node:24-bookworm bedeutet: Jobs mit runs-on: docker werden in einem node:24-bookworm-Container ausgeführt (bringt Node.js und die üblichen Build-Tools mit). Node 24 ist die aktuell aktive LTS-Linie – Node 20 ist seit April 2026 aus dem Support.

Schritt 4: Den Runner starten und Status prüfen

Jetzt startest du den ganzen Stack:

docker compose up -d

Prüfe, dass beide Container laufen:

docker compose ps

Wirf einen Blick ins Runner-Log – hier siehst du, ob die Anmeldung geklappt hat:

docker compose logs runner

Du solltest eine Zeile wie declared successfully und [poller] launched sehen – der Runner fragt Forgejo jetzt aktiv nach Jobs. In der Weboberfläche unter Administrator-Einstellungen → Actions → Runner taucht mein-runner mit einem grünen Statuspunkt und dem Label docker auf (siehe Screenshot oben). Steht er auf Inaktiv mit grünem Punkt, ist alles gut: Er ist verbunden und wartet nur auf Arbeit.

Schritt 5: Den ersten Workflow anlegen

Workflows liegen im Repository unter .forgejo/workflows/. Lege in einem beliebigen Repo die Datei .forgejo/workflows/ci.yml an:

name: CI
on: [push]
jobs:
  test:
    runs-on: docker
    steps:
      - uses: actions/checkout@v7
      - run: echo "Commit $GITHUB_SHA wird getestet"
      - run: node --version

Zerlegt:

• on: [push] – der Workflow startet bei jedem Push.
• runs-on: docker – wählt unseren Runner über das Label docker aus.
• actions/checkout@v7 – checkt den Code aus (dieselbe Action wie bei GitHub; Forgejo lädt sie automatisch aus seinem Action-Register).
• Die beiden run-Schritte geben den Commit und die Node-Version aus – ein minimales, aber echtes Beispiel, das du später durch deine echten Build-/Test-Befehle ersetzt.

Committe und pushe die Datei. Der Push löst den Workflow sofort aus.

Schritt 6: Den Lauf ansehen

Öffne im Repository den Reiter Actions. Dort erscheint dein Lauf – nach wenigen Sekunden mit einem grünen Haken:

Ein Klick auf den Lauf öffnet die Job-Ansicht mit den einzelnen Schritten und ihren Logs. Hier siehst du, wie actions/checkout das Repository klont und die Befehle nacheinander laufen:

Der node --version-Schritt gibt bei uns v24.20.0 aus – der Beweis, dass der Job wirklich im node:24-bookworm-Container gelaufen ist. Damit steht deine CI/CD: Ab jetzt kannst du in den run-Schritten testen, bauen und deployen, was du brauchst.

Wenn es nicht funktioniert

Wartung & Backups

Updates. Runner und DinD aktualisierst du wie jeden Compose-Stack:

cd /opt/forgejo-runner
docker compose pull && docker compose up -d

Halte den Runner grob auf Augenhöhe mit deiner Forgejo-Version – eine stark veraltete Runner-Version kann mit neuen Forgejo-Features Probleme bekommen. Pinne wie oben eine konkrete Version statt latest, damit Updates bewusst passieren.

Backups. Sicherungswürdig ist vor allem die .runner-Datei im Volume runner_data – sie enthält die Registrierung. Geht sie verloren, registriert sich der Runner beim nächsten Start als neuer Runner (der alte bleibt als „offline" in der Übersicht stehen und kann dort gelöscht werden). Ein Totalverlust ist kein Drama: Du holst einen neuen Token und registrierst neu. Die DinD-Daten (dind_certs, Job-Caches) sind flüchtig und müssen nicht gesichert werden.

Aufräumen. Die CI-Jobs erzeugen im DinD mit der Zeit ungenutzte Images und Layer. Räum sie gelegentlich auf, damit die Platte nicht vollläuft:

docker compose exec docker docker system prune -af

Sicherheit. Der DinD läuft privileged – behandle den Runner-Host wie ein sicherheitskritisches System: nur nötige Ports offen, keine anderen sensiblen Dienste daneben, und CI nur für Repositories, deren Workflows du kontrollierst. Wer Workflows aus fremden Forks zulässt, sollte sich vorher intensiv mit deren Risiken beschäftigen.

Was bauen wir?

Am Ende läuft Forgejo 16.0.3 als einzelner Container hinter deinem Traefik, erreichbar unter https://DEINE_DOMAIN mit automatischem Let’s-Encrypt-Zertifikat. Du legst Repositories über die Web-Oberfläche an und klonst/pushst sie wahlweise über HTTPS oder über SSH. Als Datenbank nutzen wir SQLite – für einen persönlichen oder kleinen Team-Git-Server reicht das locker und spart einen zusätzlichen Datenbank-Container. Forgejo ist der Community-Fork von Gitea und in der Selfhosting-Szene klar im Aufwind.

Warum überhaupt selbst hosten? Dein Code, deine Issues und dein Projektverlauf liegen dann ausschließlich auf deinem Server – keine Abhängigkeit von den Konditionen, Rate-Limits oder Übernahmen eines externen Anbieters, und volle Datenhoheit. Forgejo ist dabei kein abgespecktes Spielzeug: Es kann fast alles, was du von GitHub kennst (siehe Schritt 7), bleibt aber schlank genug für einen kleinen VPS.

Voraussetzungen

• Ein Server mit Debian 13 und laufendem Docker (getestet auf einem netcup VPS).
• Ein Reverse Proxy mit Traefik (das proxy-Netz und der Resolver le daraus werden vorausgesetzt) – Forgejo bringt kein eigenes HTTPS mit, Traefik übernimmt die Verschlüsselung.
• Eine (Sub-)Domain, die per A-/AAAA-Record auf deinen Server zeigt (DEINE_DOMAIN).
• Für echte Backups: verschlüsselte Backups mit Restic.

Forgejo ist genügsam und läuft schon auf dem kleinsten vServer. Wie viel Server dein geplantes Setup insgesamt braucht, schätzt dir der Server-Rechner.

Schritt für Schritt

Schritt 1: Compose-Datei anlegen

Lege einen Ordner für den Stack an und wechsle hinein:

mkdir -p /opt/forgejo && cd /opt/forgejo

Erstelle die Datei compose.yaml. Ersetze DEINE_DOMAIN durch deine echte Domain:

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:16.0.3
    container_name: forgejo
    restart: unless-stopped
    environment:
      USER_UID: 1000
      USER_GID: 1000
      FORGEJO__server__DOMAIN: DEINE_DOMAIN
      FORGEJO__server__ROOT_URL: https://DEINE_DOMAIN/
      FORGEJO__server__SSH_DOMAIN: DEINE_DOMAIN
      FORGEJO__server__START_SSH_SERVER: "true"
      FORGEJO__server__SSH_PORT: "2222"
      FORGEJO__server__SSH_LISTEN_PORT: "2222"
      FORGEJO__service__DISABLE_REGISTRATION: "true"
      FORGEJO__database__DB_TYPE: sqlite3
    volumes:
      - forgejo_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "2222:2222"
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:3000/api/healthz"]
      start_period: 30s
      start_interval: 2s
      interval: 30s
      timeout: 5s
      retries: 3
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.forgejo.rule=Host(`DEINE_DOMAIN`)"
      - "traefik.http.routers.forgejo.entrypoints=websecure"
      - "traefik.http.routers.forgejo.tls.certresolver=le"
      - "traefik.http.services.forgejo.loadbalancer.server.port=3000"
    networks: [proxy]
volumes:
  forgejo_data: {}
networks:
  proxy:
    external: true

Die wichtigsten Stellen im Detail:

• FORGEJO__…-Variablen konfigurieren Forgejo direkt über Umgebungsvariablen (Abschnitt und Schlüssel per doppeltem Unterstrich). ROOT_URL muss exakt die öffentliche HTTPS-Adresse sein, sonst zeigen Klon-Links und Weiterleitungen ins Leere.
• Git über SSH übernimmt Forgejos eingebauter SSH-Server (START_SSH_SERVER=true) – so musst du den gehärteten SSH-Zugang deines Hosts (Port 22) nicht anfassen. Er lauscht im Container auf 2222 und wird auf denselben Host-Port veröffentlicht.
• loadbalancer.server.port=3000 sagt Traefik, dass die Weboberfläche intern auf Port 3000 läuft. Nur SSH (2222) wird direkt als Port veröffentlicht – der Web-Zugriff geht ausschließlich über Traefik.
• Der Healthcheck mit start_interval: 2s ist bewusst so gesetzt (mehr dazu in „Wenn es nicht funktioniert").
• DISABLE_REGISTRATION: "true" schließt die offene Selbst-Registrierung von Anfang an – dein Git-Server steht damit nicht für Fremde offen. Dein Admin-Konto legst du trotzdem ganz normal im Erstinstallations-Wizard an (Schritt 3); alternativ könntest du es über FORGEJO__admin__*-Variablen automatisiert erzeugen.

Schritt 2: Starten und auf „healthy" warten

Starte den Container:

docker compose up -d

Prüfe den Status:

docker compose ps

Nach wenigen Sekunden steht der Container auf healthy:

NAME      IMAGE                                 SERVICE   STATUS                    PORTS
forgejo   codeberg.org/forgejo/forgejo:16.0.3   forgejo   Up 12 seconds (healthy)   22/tcp, 3000/tcp, 0.0.0.0:2222->2222/tcp, [::]:2222->2222/tcp

Das 22/tcp in der Portliste ist nur ein vom Image deklarierter Port ohne Veröffentlichung – nach außen erreichbar ist ausschließlich der 2222er, den du selbst gemappt hast.

Traefik holt jetzt im Hintergrund das Zertifikat. Prüfe von deinem Rechner aus, dass die Weboberfläche über HTTPS antwortet:

curl -s https://DEINE_DOMAIN/api/healthz

Erwartete Ausgabe – Forgejo meldet sich gesund. Solange die Erstinstallation (Schritt 3) noch nicht durch ist, antwortet der Endpunkt knapp mit Status und Slogan:

{
  "status": "pass",
  "description": "Forgejo: Beyond coding. We forge."
}

Nach dem Abschluss des Wizards listet dieselbe URL zusätzlich die Einzelprüfungen cache:ping und database:ping auf – dann steht dort auch dein Instanzname statt des Slogans.

Schritt 3: Erstinstallation & Admin-Konto

Rufe https://DEINE_DOMAIN im Browser auf. Beim ersten Start zeigt Forgejo die Erstinstallation. Die Datenbank- und Server-Einstellungen sind dank der Umgebungsvariablen bereits korrekt vorbelegt – du musst hier nur noch das Administrator-Konto anlegen (klapp den entsprechenden Abschnitt auf und trage Benutzername, E-Mail und ein starkes Passwort ein). Ein Klick auf Forgejo installieren, und nach einem kurzen Neustart landest du auf deinem leeren Dashboard:

Schritt 4: Erstes Repository anlegen

Klicke oben rechts auf das + und dann auf Neues Repository. Vergib einen Namen und setze den Haken bei Repository initialisieren (legt direkt eine README an, damit das Repo nicht leer ist):

Nach dem Anlegen siehst du die Repository-Ansicht. Über den Umschalter HTTPS / SSH bekommst du die passende Klon-Adresse:

Schritt 5: Klonen und pushen über HTTPS

Am schnellsten geht es über HTTPS – es funktioniert sofort, ohne Schlüssel einzurichten:

git clone https://DEINE_DOMAIN/DEIN_BENUTZER/mein-erstes-repo.git

Ein öffentliches Repository klonst du ohne Anmeldung – erwartete Ausgabe:

Cloning into 'mein-erstes-repo'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (3/3), done.

Bei einem privaten Repository fragt Git schon hier nach Benutzername und Passwort. Damit ist der Kreis geschlossen – du legst eine Datei an, committest sie und schiebst sie zurück auf deinen Server:

cd mein-erstes-repo
echo "Meine erste Notiz" >> notizen.txt
git add notizen.txt
git commit -m "Erste Notiz"
git push

Spätestens beim git push will Forgejo wissen, wer du bist: Git fragt nach Benutzername und Passwort. Am Ende bestätigt Git den neuen Stand auf dem Server:

To https://DEINE_DOMAIN/DEIN_BENUTZER/mein-erstes-repo.git
   f398f79..7bad57b  main -> main

Sekunden später taucht der Commit in der Weboberfläche auf – dein Code liegt jetzt versioniert auf deinem eigenen Server.

Schritt 6: Klonen und pushen über SSH

Für den täglichen Gebrauch ist SSH bequemer (kein Passwort pro Push). Hinterlege dazu deinen öffentlichen SSH-Schlüssel unter Einstellungen → SSH- / GPG-Schlüssel → Schlüssel hinzufügen:

Deinen öffentlichen Schlüssel zeigst du dir lokal mit cat ~/.ssh/id_ed25519.pub an (falls noch keiner existiert: ssh-keygen -t ed25519). Danach klonst du über SSH – beachte den Port 2222:

git clone ssh://git@DEINE_DOMAIN:2222/DEIN_BENUTZER/mein-erstes-repo.git

Damit das klappt, muss der SSH-Port in beiden Firewalls offen sein – in der UFW-Firewall (ufw allow 2222/tcp) und, falls genutzt, in der netcup-Firewall.

Schritt 7: Mehr als nur Git-Hosting

Ein Repository und Klonen sind erst der Anfang – Forgejo bringt die komplette Werkbank drumherum mit. Diese Funktionen findest du in der Navigationsleiste jedes Repositories bzw. deines Kontos:

• Issues & Pull-Requests: vollwertiges Ticket-System und Code-Review inklusive Labels, Meilensteinen und Zuweisungen – die Basis für Zusammenarbeit im Team.
• Forgejo Actions: eine zu GitHub Actions kompatible CI/CD-Engine. Bestehende .github/workflows-Dateien laufen oft ohne Änderung. Actions brauchen allerdings einen separaten Runner, der die Jobs ausführt – der gehört aus Sicherheitsgründen nicht auf den Produktiv-Host und hat ein eigenes Tutorial: Forgejo Actions: eigener CI/CD-Runner mit Docker (führt dedizierte Kerne vor: ein guter Anlass für einen Root-Server, siehe netcup-Empfehlung).
• Wiki & Releases: Dokumentation direkt am Projekt und versionierte Release-Downloads.
• Paket-Registry: Forgejo kann Container-Images, npm-, Maven-, PyPI- und weitere Pakete hosten – praktisch, wenn du eigene Artefakte ablegen willst, ohne einen weiteren Dienst zu betreiben.
• Organisationen & Teams: bündele Repositories und steuere Zugriffsrechte pro Team.

Du musst deine Projekte auch nicht von Hand umziehen: Über + → Migration importiert Forgejo ein bestehendes Repository von GitHub, GitLab oder einer anderen Forgejo-/Gitea-Instanz – inklusive Issues, Pull-Requests und Releases, nicht nur der Git-Historie. So wechselst du in wenigen Minuten von GitHub auf deinen eigenen Server, ohne etwas zu verlieren.

Wenn es nicht funktioniert

Wartung & Backups

Alles liegt im Volume forgejo_data (/data): die SQLite-Datenbank, deine Repositories und die Host-Keys des SSH-Servers. Genau dieses Volume gehört gesichert – am saubersten mit restic. Weil eine SQLite-Datei im Betrieb beschrieben wird, sicherst du sie konsistent, indem du entweder den Container kurz stoppst (docker compose stop) oder Forgejos eingebauten Dump nutzt:

docker compose exec -u git forgejo forgejo dump -t /tmp -f /tmp/forgejo-dump.zip

-u git lässt den Dump als git-Benutzer statt als root laufen (als root verweigert Forgejo den Dump). Nach /tmp statt /data, weil das git-Konto in /data selbst nicht schreiben darf (das Wurzelverzeichnis /data gehört root, nur die Unterordner wie /data/gitea und /data/git gehören dem git-Benutzer) und der Dump sich sonst rekursiv in das gepackte Datenverzeichnis schreiben würde. Die fertige Zip holst du anschließend aus dem Container heraus – dorthin, wo restic sie mitsichert:

docker compose cp forgejo:/tmp/forgejo-dump.zip ./forgejo-dump.zip

Die Zip enthält den Datenbank-Dump (forgejo-db.sql), die app.ini und alle Repository-Daten – ein vollständiger, für sich stehender Wiederherstellungspunkt.

Updates: Forgejo veröffentlicht regelmäßig neue Versionen (aktuell die 16er-Reihe). Für ein Update setzt du den neuen Tag in der compose.yaml (statt 16.0.3) und ziehst ihn:

docker compose pull && docker compose up -d

Weil die Daten im Volume liegen, bleiben Repos und Konten dabei erhalten. Pinne die Version bewusst auf einen festen Tag statt latest und wirf vor einem Major-Sprung einen Blick in die Release-Notes – dort stehen eventuelle Migrations-Hinweise. Mache außerdem vor jedem Update ein frisches Backup: ein Git-Server ohne funktionierendes Backup ist ein Klumpenrisiko für deinen gesamten Code.

Absichern: Ein öffentlich erreichbarer Git-Server ist ein lohnendes Ziel. Drei Dinge solltest du gleich erledigen: die offene Registrierung deaktivieren (siehe Schritt 3), für dein Admin-Konto unter Einstellungen → Sicherheit die Zwei-Faktor-Authentifizierung einschalten und für den Alltag ein normales Konto statt des Administrators nutzen. Halte Forgejo zeitnah aktuell – die schnellen Releases enthalten auch Sicherheitsfixes. Und veröffentliche nur die Ports, die du wirklich brauchst: nach außen genügen 443 (Traefik) und dein SSH-Git-Port 2222.