myCRM/docs/GIT_INTEGRATION.md

Git Integration - Dokumentation

Übersicht

Die Git-Integration unterstützt drei Modi:

1. Remote API (GitHub/GitLab/Gitea) - Empfohlen
2. Lokaler Clone (Git-Commands auf lokalem Repository)

Remote API

Unterstützte Provider

Provider	Status	API-Dokumentation
GitHub	✅ Implementiert	GitHub API
Gitea	✅ Implementiert	Gitea API
GitLab	🔜 Geplant	GitLab API
Bitbucket	🔜 Geplant	Bitbucket API

Vorteile

• ✅ Kein lokaler Clone nötig
• ✅ Schneller und skalierbarer
• ✅ Automatisch aktuell
• ✅ Zusätzliche Daten verfügbar (Stars, Forks, Contributors)

Nachteile

• ⚠️ Rate Limits (abhängig vom Provider)
• ⚠️ Nur für öffentliche Repos ohne Token

GitHub Integration

Repository hinzufügen (GitHub)

POST /api/git_repositories
Content-Type: application/ld+json

{
  "project": "/api/projects/1",
  "name": "Mein GitHub Projekt",
  "url": "https://github.com/username/repository",
  "branch": "main",
  "provider": "github",
  "accessToken": "ghp_XXXXXXXXXXXX"  // Optional, für private Repos
}

GitHub Personal Access Token erstellen

1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. "Generate new token (classic)"
3. Scopes auswählen:
   • repo (für private Repositories)
   • public_repo (nur für öffentliche Repositories)
4. Token kopieren und in accessToken Feld eintragen

Wichtig: Token niemals im Code committen! In Production: Environment Variable nutzen.

Gitea Integration

Repository hinzufügen (Gitea)

POST /api/git_repositories
Content-Type: application/ld+json

{
  "project": "/api/projects/1",
  "name": "Mein Gitea Projekt",
  "url": "https://gitea.example.com/username/repository",
  "branch": "main",
  "provider": "gitea",
  "accessToken": "your_gitea_token_here"  // Optional, für private Repos
}

Gitea Access Token erstellen

1. Gitea → Settings → Applications → Generate New Token
2. Token Name eingeben
3. Scopes auswählen:
   • repo (für Repository-Zugriff)
4. Token kopieren und in accessToken Feld eintragen

Besonderheiten Gitea

• Self-hosted: URL muss vollständige Instanz-URL enthalten (z.B. https://gitea.example.com/user/repo)
• API-Limit: Standardmäßig keine Rate Limits bei self-hosted Gitea
• Contributions: Werden aus Commit-Historie berechnet (max. 50 Commits pro Anfrage)

Unterstützte URL-Formate (Gitea)

https://gitea.example.com/username/repo
https://gitea.example.com/username/repo.git
git@gitea.example.com:username/repo.git

Unterstützte Provider

Provider	Status	API-Dokumentation
GitHub	✅ Implementiert	GitHub API
Gitea	✅ Implementiert	Gitea API
GitLab	🔜 Geplant	GitLab API
Bitbucket	🔜 Geplant	Bitbucket API

Lokaler Clone

Vorteile

• ✅ Funktioniert mit jedem Git-Server
• ✅ Keine API-Limits
• ✅ Volle Git-Historie verfügbar

Nachteile

• ⚠️ Benötigt Disk Space
• ⚠️ Muss regelmäßig aktualisiert werden (git pull)
• ⚠️ Git muss auf Server installiert sein

Repository hinzufügen (Lokal)

# 1. Repository lokal clonen
cd /var/www/git-repos
git clone https://github.com/username/repository.git

# 2. Via API registrieren
POST /api/git_repositories
Content-Type: application/ld+json

{
  "project": "/api/projects/1",
  "name": "Mein lokales Projekt",
  "url": "https://github.com/username/repository.git",
  "localPath": "/var/www/git-repos/repository",
  "branch": "main",
  "provider": "local"
}

Repository aktualisieren (Cron-Job)

# Crontab: Täglich um 2 Uhr morgens alle Repos pullen
0 2 * * * cd /var/www/git-repos/repository && git pull origin main

API Endpoints

Commits abrufen

GET /api/git-repos/{id}/commits?branch=main&limit=100

Contributions abrufen (Wochenstatistik)

GET /api/git-repos/{id}/contributions?branch=main

Branches auflisten

GET /api/git-repos/{id}/branches

Repository validieren

GET /api/git-repos/{id}/validate

Environment-Variablen (.env)

# Optional: GitHub Token für höhere Rate Limits
GITHUB_TOKEN=ghp_XXXXXXXXXXXX

# Optional: Gitea Token für private Repos
GITEA_TOKEN=your_gitea_token_here

# Optional: GitLab Token
GITLAB_TOKEN=glpat-XXXXXXXXXXXX

Rate Limits

GitHub

• Ohne Token: 60 Requests/Stunde
• Mit Token: 5000 Requests/Stunde
• Enterprise: 15000 Requests/Stunde

Gitea (Self-hosted)

• Standard: Keine Limits (konfigurierbar durch Admin)
• Empfehlung: Token verwenden für private Repos

Empfehlung

Für Production-Umgebungen immer einen Token verwenden und Caching implementieren.

Beispiel: Repository über UI hinzufügen

1. Projekt öffnen
2. Tab "Git Repositories" öffnen
3. "Repository hinzufügen" klicken
4. Provider auswählen: github oder gitea
5. URL eintragen:
   • GitHub: https://github.com/username/repo
   • Gitea: https://gitea.example.com/username/repo
6. Optional: Access Token eintragen (für private Repos)
7. Speichern

Troubleshooting

"Failed to fetch commits: 403 Forbidden"

→ Rate Limit erreicht. Token hinzufügen oder warten.

"Invalid GitHub URL format"

→ URL muss Format haben: https://github.com/owner/repo oder git@github.com:owner/repo.git

"Invalid Gitea URL format"

→ URL muss vollständige Gitea-Instanz beinhalten: https://gitea.example.com/owner/repo

"No data source configured"

→ Weder provider noch localPath gesetzt. Eines von beiden ist erforderlich.

Gitea: "Failed to fetch commits"

→ Prüfe:

• Ist die Gitea-Instanz erreichbar?
• Ist der Token gültig?
• Hat der Token die nötigen Rechte (repo scope)?
• Ist das Repository öffentlich oder benötigt einen Token?