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](https://docs.github.com/en/rest) |
| Gitea     | ✅ Implementiert | [Gitea API](https://docs.gitea.io/en-us/api-usage/) |
| GitLab    | 🔜 Geplant | [GitLab API](https://docs.gitlab.com/ee/api/) |
| Bitbucket | 🔜 Geplant | [Bitbucket API](https://developer.atlassian.com/cloud/bitbucket/rest/) |

### 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)

```bash
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)

```bash
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](https://docs.github.com/en/rest) |
| Gitea     | ✅ Implementiert | [Gitea API](https://docs.gitea.io/en-us/api-usage/) |
| GitLab    | 🔜 Geplant | [GitLab API](https://docs.gitlab.com/ee/api/) |
| Bitbucket | 🔜 Geplant | [Bitbucket API](https://developer.atlassian.com/cloud/bitbucket/rest/) |

## 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)

```bash
# 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)

```bash
# 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)

```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?