Forgejo: eigener Git-Server mit Docker statt GitHub

GitHub ist bequem, aber nicht jedes Repository gehört dorthin. Die Konfiguration Deines Heimservers, private Notizen in Markdown, Skripte mit Hinweisen auf Deine Infrastruktur oder ein Projekt für einen Kunden mit strengen Vorgaben liegen besser auf eigener Hardware.

Forgejo ist ein schlanker Git-Server mit Weboberfläche, Issues, Pull Requests, Wiki und eigener CI. Er entstand 2022 als Abspaltung von Gitea und wird von einer gemeinnützigen Gemeinschaft entwickelt, unter anderem für die Plattform Codeberg. Forgejo läuft schon auf einem Raspberry Pi flüssig. Diese Anleitung installiert ihn mit Docker, richtet SSH ein und holt Repositories von GitHub herüber. Stand ist Forgejo 17. Grundlage ist die offizielle Installationsanleitung für Docker.

Was Du brauchst

• Einen Linux-Server oder Raspberry Pi mit Docker und dem Compose-Plugin. Für ein paar Benutzer reicht 1 GB RAM.
• Für Zugriff von außen eine Subdomain wie git.example.com und einen Reverse Proxy für HTTPS. Für reine Nutzung im Heimnetz oder über ein VPN geht es auch ohne.

Schritt 1: Forgejo starten

Lege einen Ordner an und erstelle die Compose-Datei:

mkdir -p ~/forgejo
cd ~/forgejo
nano compose.yml

Füge diesen Inhalt ein. Er entspricht dem Beispiel aus der offiziellen Doku:

services:
  server:
    image: codeberg.org/forgejo/forgejo:17
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    volumes:
      - ./forgejo:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"

Die Zeilen im Überblick:

• image nutzt die Hauptversion 17. Damit bekommst Du beim Aktualisieren Korrekturen innerhalb dieser Version, aber keinen ungeplanten Sprung zur nächsten Hauptversion.
• USER_UID und USER_GID legen fest, mit welchen Rechten Forgejo Dateien schreibt. Nimm die Werte Deines Benutzers, die Dir id -u und id -g anzeigen. Der Ordner ./forgejo muss diesem Benutzer gehören, sonst startet der Container nicht.
• Port 3000 ist die Weboberfläche, Port 222 auf dem Host leitet an den SSH-Dienst im Container weiter. Port 22 bleibt so für den normalen SSH-Zugang zum Server frei.

Forgejo nutzt in dieser Form SQLite als Datenbank. Das genügt für private und kleine Team-Installationen völlig.

docker compose up -d

Schritt 2: Die Ersteinrichtung

Öffne http://IP-DES-SERVERS:3000 im Browser. Forgejo zeigt eine Seite mit Grundeinstellungen. Die meisten Vorgaben passen, prüfe aber diese Felder:

• Server-Domain und Basis-URL: Trag die Adresse ein, unter der Forgejo später erreichbar ist, etwa https://git.example.com/. Ohne öffentliche Domain nimmst Du die IP-Adresse mit Port 3000.
• SSH-Server-Port: 222, damit die Klon-Adressen in der Oberfläche stimmen.
• Registrierung deaktivieren: Unter den optionalen Einstellungen setzt Du den Haken, damit sich nicht jeder ein Konto anlegen kann. Weitere Benutzer legst Du später als Administrator selbst an.
• Administratorkonto: Lege es direkt auf dieser Seite an.

Klicke auf Forgejo installieren. Nach einigen Sekunden landest Du angemeldet auf der Startseite.

Schritt 3: HTTPS vor die Weboberfläche

Soll Forgejo aus dem Internet erreichbar sein, gehört HTTPS davor. Mit Caddy reichen drei Zeilen in der Datei /etc/caddy/Caddyfile:

git.example.com {
    reverse_proxy localhost:3000
}

Lade die Konfiguration mit sudo systemctl reload caddy neu. Läuft auf dem Server Coolify oder ein anderer Proxy, trägst Du die Domain dort ein. Den SSH-Port 222 öffnest Du in der Firewall nur, wenn Du auch von außen per SSH pushen willst.

Schritt 4: SSH-Schlüssel hinterlegen und klonen

Öffne in Forgejo oben rechts Dein Profil, dann Einstellungen > SSH-/GPG-Schlüssel und füge Deinen öffentlichen Schlüssel hinzu. Den Inhalt zeigt Dir am Mac cat ~/.ssh/id_ed25519.pub. Wie Du ein Schlüsselpaar anlegst, steht in Mac für Entwickler einrichten: der Leitfaden für 2026.

Damit Du beim Klonen nicht jedes Mal den Port angeben musst, ergänzt Du am Mac die Datei ~/.ssh/config:

Host git.example.com
    Port 222
    User git

Teste die Verbindung:

ssh -T git@git.example.com

Forgejo antwortet mit einer Begrüßung, die Deinen Benutzernamen nennt. Danach klonst Du Repositories wie gewohnt mit der SSH-Adresse aus der Weboberfläche.

Schritt 5: Repositories von GitHub übernehmen

Forgejo bringt eine Migration mit, die nicht nur den Code, sondern auf Wunsch auch Issues, Pull Requests, Releases und Wiki übernimmt.

1. Klicke oben rechts auf das Plus-Symbol und wähle Neue Migration.
2. Wähle GitHub.
3. Gib die Adresse des Repositorys ein. Für private Repositories brauchst Du ein persönliches Zugriffstoken von GitHub mit Leserechten, das Du in den GitHub-Einstellungen unter den Entwicklereinstellungen erzeugst.
4. Wähle, welche Teile übernommen werden sollen, und starte die Migration.

Alternativ kannst Du ein Repository als Spiegel anlegen. Forgejo holt dann in regelmäßigen Abständen den aktuellen Stand von GitHub. So hast Du eine Sicherungskopie Deiner GitHub-Projekte auf eigener Hardware, ohne Deinen Arbeitsablauf zu ändern.

Sichern und aktualisieren

Alle Daten liegen im Ordner ~/forgejo/forgejo: Repositories, Datenbank und Konfiguration. Sicher ihn regelmäßig, am besten bei kurz gestopptem Container, damit die SQLite-Datenbank konsistent ist. Ein Updatebefehl für die aktuelle Hauptversion sieht so aus:

docker compose pull
docker compose up -d

Für den Sprung auf eine neue Hauptversion änderst Du die Zahl im Image und liest vorher die Release Notes. Wie Du Dich über neue Versionen benachrichtigen lässt, zeigt Docker-Container aktualisieren: Diun statt Watchtower.

Ausblick: Forgejo Actions

Forgejo hat ein eigenes CI-System, das sich bewusst an GitHub Actions anlehnt. Workflows liegen in .forgejo/workflows/ und sind in derselben YAML-Syntax geschrieben, viele GitHub-Workflows laufen mit kleinen Anpassungen. Für die Ausführung brauchst Du einen separaten Runner, den Forgejo Runner, der die Jobs in Containern startet. Seine Einrichtung beschreibt die Doku unter Forgejo Runner installation. Für den Start lohnt es sich, den Git-Server erst einmal ohne CI zu nutzen und Actions später dazuzunehmen.

Typische Fehler

Der Container startet nicht, im Log steht etwas von permission denied. Der Ordner ./forgejo gehört einem anderen Benutzer als dem in USER_UID. Korrigiere das mit sudo chown -R 1000:1000 ~/forgejo/forgejo, wobei Du 1000 durch Deine Werte ersetzt.

ssh -T fragt nach einem Passwort. Der Port stimmt nicht, und Du landest beim normalen SSH des Servers statt bei Forgejo. Prüf den Eintrag in ~/.ssh/config.

Klon-Adressen in der Oberfläche zeigen die falsche Domain. Die Basis-URL aus der Ersteinrichtung steht in der Datei ~/forgejo/forgejo/gitea/conf/app.ini unter ROOT_URL. Korrigiere sie dort und starte den Container neu.

Fazit

Forgejo gibt Dir in einer Viertelstunde ein vollwertiges Git-Hosting mit allem, was Du von GitHub kennst, auf eigener Hardware und ohne Abhängigkeit von einem Konzern. Besonders gut passt es zu Konfigurationen und Infrastruktur-Code. Wenn darin Passwörter vorkommen, gehören sie verschlüsselt ins Repository, wie es sops und age: .env-Dateien verschlüsselt in Git zeigt.