Git & SSH Setup

Diese Anleitung beschreibt das Einrichten von Git und SSH für den Development-Workflow bei ITeas. Alle Commits werden mit einem SSH-Key signiert. Als Git-Server wird GitLab unter git.styrion.net verwendet.

Siehe auch: Git Workflow für die Branching-Strategien und Release-Prozesse.

Voraussetzungen

• Git ist installiert
• OpenSSH-Client ist installiert (unter Windows: Optionale Features > OpenSSH-Client)
• Zugang zum GitLab unter git.styrion.net

SSH-Key erstellen

Einen neuen SSH-Key erstellen:

ssh-keygen -t ed25519 -C "vorname.nachname@iteas.at"

• Speicherort bestätigen (Standard: ~/.ssh/id_ed25519) oder einen eigenen Pfad angeben
• Eine sichere Passphrase vergeben

TIP

Ed25519 ist der empfohlene Algorithmus für neue Keys. Er ist sicherer und performanter als RSA. Bestehende RSA-Keys können weiterhin verwendet werden.

SSH-Key in GitLab hinterlegen

Der SSH-Key muss in GitLab für die Authentifizierung und das Signieren von Commits hinterlegt werden.

1. Den öffentlichen Key kopieren:

   cat ~/.ssh/id_ed25519.pub

2. In GitLab unter Preferences > SSH Keys den Key hinzufügen:

   • Usage Type auf Authentication & Signing setzen (oder jeweils separat als Authentication und Signing)

INFO

Der gleiche Key kann für beides verwendet werden. GitLab benötigt die explizite Zuordnung als Signing-Key, damit signierte Commits als "Verified" angezeigt werden.

Git konfigurieren

Benutzerinformationen

git config --global user.name "Vorname Nachname"
git config --global user.email "vorname.nachname@iteas.at"

SSH Commit-Signierung einrichten

# SSH als Signatur-Format setzen
git config --global gpg.format ssh

# Alle Commits automatisch signieren
git config --global commit.gpgsign true

Signing-Key konfigurieren

Der Signing-Key kann auf zwei Arten angegeben werden:

Variante 1: Key-Inhalt direkt (empfohlen)

Den Inhalt des öffentlichen Keys direkt als signingkey setzen:

git config --global user.signingkey "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... vorname.nachname@iteas.at"

Den vollständigen Inhalt von ~/.ssh/id_ed25519.pub (bzw. id_rsa.pub) verwenden.

Variante 2: Dateipfad

Alternativ kann auch der Pfad zum öffentlichen Key angegeben werden:

git config --global user.signingkey ~/.ssh/id_ed25519.pub

WARNING

Wenn ein SSH-Agent mit Passwortmanager (z.B. KeePassXC) verwendet wird, liegt der öffentliche Key möglicherweise nicht als Datei auf dem System. In diesem Fall muss Variante 1 (Key-Inhalt direkt) verwendet werden.

Allowed Signers Datei (optional)

Damit Git lokal signierte Commits verifizieren kann, wird eine allowed_signers-Datei benötigt. Dies ist für die Signierung in GitLab nicht erforderlich, aber nützlich um Signaturen lokal mit git log --show-signature zu prüfen.

1. Datei erstellen:

   touch ~/.ssh/allowed_signers

2. Eigenen Key eintragen (Format: email key-type key):

   vorname.nachname@iteas.at ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...

3. Git die Datei bekannt machen:

   git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers

Verbindung testen

ssh -T git@git.styrion.net

Bei Erfolg sollte eine Willkommensnachricht von GitLab erscheinen:

Welcome to GitLab, @benutzername!

SSH nur intern verfügbar

SSH-Zugriff auf GitLab ist nur über das interne Netzwerk möglich. Wenn extern ohne Remote-Access-Tool (z.B. VPN) gearbeitet wird, muss stattdessen HTTPS mit einem persönlichen Access Token verwendet werden.

Repositories können dann per HTTPS geklont werden:

git clone https://git.styrion.net/gruppe/projekt.git

Die Commit-Signierung mit SSH funktioniert weiterhin unabhängig davon, da diese lokal erfolgt.

Windows: SSH-Client konfigurieren

Unter Windows muss Git explizit der Windows OpenSSH-Client zugewiesen werden, damit der SSH-Agent korrekt verwendet wird:

git config --global core.sshCommand "C:\\Windows\\System32\\OpenSSH\\ssh.exe"

Git Credential Manager

Der Git Credential Manager (GCM) speichert Zugangsdaten für HTTPS-basierte Git-Operationen sicher im Windows Credential Store. Er unterstützt Multi-Faktor-Authentifizierung und funktioniert mit GitLab, GitHub, Azure DevOps und Bitbucket.

GCM wird bei der Installation von Git for Windows standardmäßig mitinstalliert. Falls nicht, kann er separat installiert werden.

Nach der Installation wird GCM als Credential Helper konfiguriert:

git config --global credential.helper "C:/Users/BENUTZERNAME/AppData/Local/Programs/Git Credential Manager/git-credential-manager.exe"

Für das ITeas GitLab zusätzlich den Provider auf generic setzen:

git config --global credential.https://git.styrion.net.provider generic

INFO

Beim ersten git push oder git pull über HTTPS öffnet sich automatisch ein Anmeldefenster. Die Zugangsdaten werden danach im Windows Credential Store gespeichert und bei zukünftigen Operationen wiederverwendet.

Zusammenfassung Windows .gitconfig

Die resultierende ~/.gitconfig unter Windows sollte in etwa so aussehen:

[user]
    name = Vorname Nachname
    email = vorname.nachname@iteas.at
    signingkey = ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... vorname.nachname@iteas.at

[gpg]
    format = ssh

[commit]
    gpgsign = true

[core]
    sshCommand = 'C:\\Windows\\System32\\OpenSSH\\ssh.exe'

[credential "https://git.styrion.net"]
    provider = generic

[credential]
    helper = C:/Users/BENUTZERNAME/AppData/Local/Programs/Git Credential Manager/git-credential-manager.exe

WSL Setup (Windows SSH-Client verwenden)

Wenn unter WSL (Windows Subsystem for Linux) entwickelt wird, empfiehlt es sich den Windows OpenSSH-Client zu verwenden, anstatt einen eigenen SSH-Client in WSL zu konfigurieren. So müssen Keys und Agent nicht doppelt verwaltet werden.

Warum den Windows SSH-Client?

• Der SSH-Key und der SSH-Agent existieren nur einmal (auf der Windows-Seite)
• KeePassXC und andere Windows-Tools können den Agent nutzen
• Keine doppelte Key-Verwaltung nötig

Konfiguration

Git in WSL so konfigurieren, dass der Windows SSH-Client verwendet wird:

git config --global core.sshCommand ssh.exe

Da ssh.exe von Windows im WSL-PATH verfügbar ist, reicht der kurze Befehl. Git in WSL nutzt damit den Windows-SSH-Client für alle SSH-Operationen (clone, push, pull, fetch).

Signing-Key in WSL

Da der signingkey als Key-Inhalt (nicht als Dateipfad) gesetzt wird, ist in WSL keine Pfadanpassung nötig. Die gleiche Konfiguration wie unter Windows kann verwendet werden:

git config --global user.signingkey "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... vorname.nachname@iteas.at"

Falls stattdessen ein Dateipfad verwendet wird, muss dieser auf den Windows-Pfad zeigen:

git config --global user.signingkey /mnt/c/Users/BENUTZERNAME/.ssh/id_ed25519.pub

WARNING

BENUTZERNAME durch den eigenen Windows-Benutzernamen ersetzen.

Zusammenfassung WSL .gitconfig

Die resultierende ~/.gitconfig in WSL sollte in etwa so aussehen:

[user]
    name = Vorname Nachname
    email = vorname.nachname@iteas.at
    signingkey = ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... vorname.nachname@iteas.at

[gpg]
    format = ssh

[commit]
    gpgsign = true

[core]
    sshCommand = ssh.exe

Optional: SSH-Agent

Der SSH-Agent speichert die entschlüsselte Passphrase im Arbeitsspeicher, sodass sie nicht bei jeder Git-Operation erneut eingegeben werden muss.

Windows OpenSSH Agent

Den OpenSSH Authentication Agent Service in Windows aktivieren:

1. Services (services.msc) öffnen
2. OpenSSH Authentication Agent suchen
3. Starttyp auf Automatisch setzen und den Dienst starten

Key zum Agent hinzufügen:

ssh-add $env:USERPROFILE\.ssh\id_ed25519

SSH-Agent mit KeePassXC

KeePassXC bietet eine integrierte SSH-Agent-Integration. Dabei werden SSH-Keys direkt aus der KeePassXC-Datenbank verwaltet: Beim Entsperren der Datenbank werden die konfigurierten Keys automatisch in den SSH-Agent geladen, beim Sperren wieder entfernt. So muss kein separates ssh-add ausgeführt werden und die Keys sind nur verfügbar, solange die Datenbank offen ist.

KeePassXC einrichten

1. In KeePassXC: Einstellungen > SSH Agent > SSH Agent Integration aktivieren
2. Unter Windows die Option Use OpenSSH for Windows instead of Pageant aktivieren

SSH-Key im Datenbankeintrag konfigurieren

1. Einen neuen Eintrag in der Datenbank erstellen oder einen bestehenden bearbeiten
2. Im Bereich Erweitert: Den privaten Key (z.B. id_ed25519) als Attachment hinzufügen
3. Im Tab SSH Agent:
   • Das zuvor hinzugefügte Attachment als Private Key auswählen
   • Add key to agent when database is opened/unlocked aktivieren
   • Remove key from agent when database is closed/locked aktivieren

Vorteile

• Automatisches Laden/Entfernen der Keys beim Entsperren/Sperren der Datenbank
• Kein separates ssh-add nötig
• SSH-Keys sind zentral und verschlüsselt in der KeePassXC-Datenbank gespeichert
• Funktioniert sowohl nativ unter Windows als auch über WSL (wenn der Windows SSH-Client konfiguriert ist)

TIP

Bei Verwendung von KeePassXC als SSH-Agent muss der Windows OpenSSH Authentication Agent Service nicht laufen. KeePassXC ersetzt diesen.

Hinweis: Andere Passwortmanager

Andere Passwortmanager wie z.B. 1Password bieten ebenfalls SSH-Agent-Unterstützung. Manche bringen ein eigenes Signing-Programm mit, das über gpg.ssh.program konfiguriert wird:

# Beispiel für 1Password unter WSL
git config --global gpg.ssh.program "/mnt/c/Users/BENUTZERNAME/AppData/Local/Microsoft/WindowsApps/op-ssh-sign-wsl.exe"

Bei KeePassXC ist dies nicht nötig, da KeePassXC den Key über den Standard Windows OpenSSH Agent bereitstellt.

Fehlerbehebung

Commit schlägt fehl bei gesperrtem Passwortmanager

Wenn der SSH-Key über einen Passwortmanager (z.B. KeePassXC) verwaltet wird und die Datenbank gesperrt ist, steht der Key dem SSH-Agent nicht zur Verfügung. Git-Commits schlagen dann mit einem Signierungsfehler fehl.

Lösung: Die KeePassXC-Datenbank entsperren, damit der SSH-Key wieder in den Agent geladen wird.

"Permission denied (publickey)"

• Prüfen ob der SSH-Key in GitLab hinterlegt ist
• Prüfen ob der richtige Key verwendet wird: ssh -vT git@git.styrion.net
• Prüfen ob die SSH-Config korrekt ist

Commits werden in GitLab nicht als "Verified" angezeigt

• Prüfen ob der SSH-Key in GitLab als Signing-Key hinterlegt ist
• Prüfen ob die E-Mail-Adresse in der Git-Config mit der in GitLab übereinstimmt
• Prüfen ob gpg.format auf ssh gesetzt ist: git config --global gpg.format

WSL: SSH-Verbindung schlägt fehl

• Prüfen ob der Pfad zum Windows SSH-Client korrekt ist:

  ls -la /mnt/c/Windows/System32/OpenSSH/ssh.exe

• Prüfen ob der Windows OpenSSH-Client installiert ist