Claude
45b15c7fd5
Complete implementation of automated GitHub repository synchronization: - Webhook-based auto-sync from GitHub - Multi-repository support with branch selection - Web dashboard for management - Manual sync and rollback functionality - Comprehensive logging and monitoring Located in /gitpusher/ subdirectory as standalone application.
448 lines
11 KiB
Markdown
448 lines
11 KiB
Markdown
# Projektstruktur
|
||
|
||
## Übersicht
|
||
|
||
```
|
||
/gitpusher/
|
||
│
|
||
├── 📄 README.md # Hauptdokumentation
|
||
├── 📄 INSTALL.md # Schnellstart-Installation
|
||
├── 📄 PROJECT_STRUCTURE.md # Diese Datei
|
||
├── 🔒 .htaccess # Hauptsicherheitskonfiguration
|
||
├── 📝 .gitignore # Git-Ignore-Regeln
|
||
│
|
||
├── 📁 public/ # Web-Root (Apache DocumentRoot)
|
||
│ ├── 🌐 index.php # Dashboard (Frontend)
|
||
│ ├── 🔗 webhook.php # Webhook-Endpoint für GitHub
|
||
│ │
|
||
│ ├── 📁 api/ # REST API Endpunkte
|
||
│ │ ├── repos.php # Repository-CRUD-Operationen
|
||
│ │ ├── sync.php # Manueller Sync-Trigger
|
||
│ │ ├── rollback.php # Rollback zu älterem Commit
|
||
│ │ └── log.php # Log-Abfrage
|
||
│ │
|
||
│ ├── 📁 css/
|
||
│ │ └── style.css # Komplettes Dashboard-Styling
|
||
│ │
|
||
│ └── 📁 js/
|
||
│ └── app.js # Frontend-Logik & AJAX
|
||
│
|
||
├── 📁 data/ # Datenspeicher (NICHT web-zugänglich!)
|
||
│ ├── 🔒 .htaccess # Zugriff komplett verweigern
|
||
│ ├── 📊 config.json # Repository-Konfigurationen
|
||
│ ├── 📜 log.json # Alle Log-Einträge
|
||
│ └── 🔐 secrets.json # GitHub PAT & Webhook Secrets
|
||
│
|
||
└── 📁 src/ # PHP Backend-Klassen
|
||
├── 🔒 .htaccess # Zugriff komplett verweigern
|
||
├── ConfigManager.php # JSON-Dateiverwaltung
|
||
├── Logger.php # Logging-System
|
||
└── GitHandler.php # Git-Operationen (clone, pull, revert)
|
||
```
|
||
|
||
## 📂 Detaillierte Beschreibung
|
||
|
||
### `/public/` - Web-Root
|
||
|
||
**Apache DocumentRoot** - Einziger Ordner, der über HTTP erreichbar ist.
|
||
|
||
#### `index.php` - Dashboard
|
||
- Haupt-Frontend der Anwendung
|
||
- Zeigt alle Repositories mit Status
|
||
- Statistiken (Anzahl Repos, Sync-Status, etc.)
|
||
- Log-Anzeige der letzten Ereignisse
|
||
- Modals für: Repository hinzufügen, Rollback, Webhook-Info
|
||
|
||
#### `webhook.php` - GitHub Webhook Endpoint
|
||
- Empfängt POST-Requests von GitHub
|
||
- Verifiziert Webhook-Signatur (HMAC SHA-256)
|
||
- Prüft, ob Push zum konfigurierten Branch gehört
|
||
- Triggert automatischen `git pull`
|
||
- Loggt alle Ereignisse
|
||
|
||
#### `/api/` - REST API
|
||
|
||
##### `repos.php`
|
||
- **GET**: Liste aller Repositories oder einzelnes Repository
|
||
- **POST**: Neues Repository hinzufügen (+ initial clone)
|
||
- **PUT**: Repository-Einstellungen aktualisieren
|
||
- **DELETE**: Repository aus Config entfernen (optional: Dateien löschen)
|
||
|
||
##### `sync.php`
|
||
- **POST**: Manuellen Sync durchführen
|
||
- Führt `git pull` für angegebenes Repository aus
|
||
- Gibt Anzahl geänderter Dateien zurück
|
||
|
||
##### `rollback.php`
|
||
- **GET**: Liste der letzten Commits (für Rollback-Auswahl)
|
||
- **POST**: Rollback zu bestimmtem Commit durchführen
|
||
- Nutzt `git revert` (sicher, keine Commits gelöscht)
|
||
|
||
##### `log.php`
|
||
- **GET**: Log-Einträge abrufen
|
||
- Filter: Repository-ID, Log-Type, Limit, Offset
|
||
- Gibt Statistiken zurück (Erfolg/Fehler/Warnung)
|
||
|
||
#### `/css/style.css`
|
||
- Modernes, responsives Design
|
||
- CSS Custom Properties (CSS Variables)
|
||
- Mobile-First Ansatz
|
||
- Animationen für Toasts, Modals, Cards
|
||
|
||
#### `/js/app.js`
|
||
- Frontend-State-Management
|
||
- AJAX-Calls zu allen API-Endpunkten
|
||
- Modal-Handling
|
||
- Toast-Notifications
|
||
- Auto-Refresh (alle 30 Sekunden)
|
||
|
||
---
|
||
|
||
### `/data/` - Datenspeicher
|
||
|
||
**Sicherheit**: `.htaccess` verweigert jeden Web-Zugriff!
|
||
|
||
#### `config.json`
|
||
```json
|
||
{
|
||
"repositories": [
|
||
{
|
||
"id": "repo_uniqueid123",
|
||
"name": "Meine Website",
|
||
"repo_url": "https://github.com/user/repo.git",
|
||
"branch": "main",
|
||
"target_path": "/var/www/website",
|
||
"auto_sync": true,
|
||
"status": "synced",
|
||
"created_at": "2025-12-06 10:00:00",
|
||
"last_sync": "2025-12-06 14:30:00",
|
||
"last_commit": "abc123def456..."
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### `log.json`
|
||
```json
|
||
{
|
||
"entries": [
|
||
{
|
||
"id": "log_uniqueid456",
|
||
"timestamp": "2025-12-06 14:30:00",
|
||
"repo_id": "repo_uniqueid123",
|
||
"type": "success",
|
||
"message": "Pull completed successfully",
|
||
"details": {
|
||
"files_changed": 3,
|
||
"old_commit": "abc123d",
|
||
"new_commit": "def456a"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### `secrets.json`
|
||
```json
|
||
{
|
||
"github_pat": "ghp_YourPersonalAccessTokenHere",
|
||
"webhook_secrets": {
|
||
"repo_uniqueid123": "generatedWebhookSecretHere"
|
||
}
|
||
}
|
||
```
|
||
|
||
**Berechtigungen**: `chmod 600` (nur Owner kann lesen/schreiben)
|
||
|
||
---
|
||
|
||
### `/src/` - Backend-Klassen
|
||
|
||
**Sicherheit**: `.htaccess` verweigert jeden Web-Zugriff!
|
||
|
||
#### `ConfigManager.php`
|
||
**Verantwortlichkeiten:**
|
||
- JSON-Dateien lesen/schreiben
|
||
- Repository-CRUD-Operationen
|
||
- Webhook-Secret-Verwaltung
|
||
- GitHub PAT verwalten
|
||
|
||
**Wichtige Methoden:**
|
||
```php
|
||
getRepositories() // Alle Repos
|
||
getRepository($id) // Einzelnes Repo
|
||
addRepository($data) // Neues Repo
|
||
updateRepository($id, $updates) // Repo aktualisieren
|
||
deleteRepository($id) // Repo löschen
|
||
getGitHubToken() // PAT abrufen
|
||
setWebhookSecret($id, $secret) // Webhook Secret speichern
|
||
```
|
||
|
||
#### `Logger.php`
|
||
**Verantwortlichkeiten:**
|
||
- Log-Einträge erstellen
|
||
- Logs nach Typ/Repo filtern
|
||
- Statistiken generieren
|
||
- Auto-Bereinigung (max. 1000 Einträge)
|
||
|
||
**Wichtige Methoden:**
|
||
```php
|
||
success($repoId, $message, $details) // ✅ Erfolg loggen
|
||
error($repoId, $message, $details) // ❌ Fehler loggen
|
||
warning($repoId, $message, $details) // ⚠️ Warnung loggen
|
||
info($repoId, $message, $details) // ℹ️ Info loggen
|
||
getAll($limit, $offset) // Alle Logs
|
||
getByRepository($repoId) // Logs für Repo
|
||
getStats() // Statistiken
|
||
```
|
||
|
||
#### `GitHandler.php`
|
||
**Verantwortlichkeiten:**
|
||
- Git-Befehle ausführen
|
||
- Repository klonen
|
||
- Pull durchführen
|
||
- Revert zu älterem Commit
|
||
- Commit-Historie abrufen
|
||
- Merge-Konflikte erkennen
|
||
|
||
**Wichtige Methoden:**
|
||
```php
|
||
cloneRepository($repoId, $url, $path, $branch) // Initial clone
|
||
pull($repoId, $path, $branch) // git pull
|
||
revert($repoId, $path, $commitHash) // git revert
|
||
getCurrentCommit($path) // Aktueller Commit
|
||
getCommitHistory($path, $limit) // Commit-Liste
|
||
getStatus($path) // git status
|
||
getRemoteBranches($url) // Verfügbare Branches
|
||
```
|
||
|
||
**Sicherheit:**
|
||
- Alle Shell-Befehle mit `escapeshellarg()` escaped
|
||
- GitHub PAT wird in URL eingebettet für Auth
|
||
- Fehlerbehandlung mit Try-Catch
|
||
|
||
---
|
||
|
||
## 🔐 Sicherheitskonzept
|
||
|
||
### 1. Zugriffskontrolle
|
||
|
||
**Web-zugänglich**: Nur `/public/`
|
||
|
||
**Blockiert**:
|
||
- `/data/` (enthält Secrets & Konfiguration)
|
||
- `/src/` (PHP-Klassen)
|
||
- Alle `.json` Dateien
|
||
- `.git` Verzeichnisse
|
||
|
||
### 2. Webhook-Sicherheit
|
||
|
||
- HMAC SHA-256 Signatur-Verifizierung
|
||
- Unique Secret pro Repository
|
||
- Timing-Safe Vergleich (`hash_equals()`)
|
||
|
||
### 3. Datei-Berechtigungen
|
||
|
||
```bash
|
||
/gitpusher/ 755 (www-data:www-data)
|
||
/gitpusher/public/ 755
|
||
/gitpusher/data/ 755
|
||
/gitpusher/data/*.json 600 (nur Owner lesen/schreiben)
|
||
/gitpusher/src/ 755
|
||
```
|
||
|
||
### 4. Input-Validierung
|
||
|
||
- Alle User-Inputs werden validiert
|
||
- JSON-Parsing mit Fehlerbehandlung
|
||
- Repository-URLs werden geprüft
|
||
- SQL-Injection nicht möglich (keine DB)
|
||
- XSS-Prevention durch `escapeHtml()` im Frontend
|
||
|
||
### 5. Git-Sicherheit
|
||
|
||
- Alle Git-Befehle laufen als `www-data` User
|
||
- Shell-Injection-Prevention durch `escapeshellarg()`
|
||
- GitHub PAT mit minimalen Berechtigungen (nur `repo`)
|
||
|
||
---
|
||
|
||
## 🔄 Datenfluss
|
||
|
||
### Automatischer Sync (Webhook)
|
||
|
||
```
|
||
GitHub Push Event
|
||
↓
|
||
webhook.php
|
||
↓
|
||
1. Payload empfangen
|
||
2. JSON dekodieren
|
||
3. Signature verifizieren (HMAC SHA-256)
|
||
4. Repository in Config finden
|
||
5. Branch prüfen
|
||
↓
|
||
GitHandler::pull()
|
||
↓
|
||
1. Aktuellen Commit speichern
|
||
2. git pull ausführen
|
||
3. Auf Merge-Konflikte prüfen
|
||
4. Geänderte Dateien zählen
|
||
↓
|
||
Logger::success/error()
|
||
↓
|
||
ConfigManager::updateRepository()
|
||
↓
|
||
Status aktualisiert in config.json
|
||
```
|
||
|
||
### Manueller Sync
|
||
|
||
```
|
||
User klickt "Sync"-Button
|
||
↓
|
||
JavaScript: syncRepository(repoId)
|
||
↓
|
||
AJAX POST → api/sync.php
|
||
↓
|
||
GitHandler::pull()
|
||
↓
|
||
Logger::log()
|
||
↓
|
||
Response → JavaScript
|
||
↓
|
||
Dashboard-Refresh
|
||
```
|
||
|
||
### Repository hinzufügen
|
||
|
||
```
|
||
User füllt Formular aus
|
||
↓
|
||
JavaScript: addRepository(event)
|
||
↓
|
||
AJAX POST → api/repos.php
|
||
↓
|
||
1. Input validieren
|
||
2. ConfigManager::addRepository()
|
||
3. Webhook Secret generieren
|
||
4. GitHandler::cloneRepository()
|
||
↓
|
||
5. Logger::success()
|
||
6. Webhook-Info zurückgeben
|
||
↓
|
||
Modal mit Webhook-Daten anzeigen
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 Abhängigkeiten
|
||
|
||
### PHP-Klassen
|
||
|
||
```
|
||
webhook.php
|
||
├── ConfigManager
|
||
├── Logger
|
||
└── GitHandler
|
||
└── Logger
|
||
└── ConfigManager
|
||
|
||
api/repos.php
|
||
├── ConfigManager
|
||
├── Logger
|
||
└── GitHandler
|
||
|
||
api/sync.php
|
||
├── ConfigManager
|
||
├── Logger
|
||
└── GitHandler
|
||
|
||
api/rollback.php
|
||
├── ConfigManager
|
||
├── Logger
|
||
└── GitHandler
|
||
|
||
api/log.php
|
||
├── ConfigManager
|
||
└── Logger
|
||
```
|
||
|
||
### Frontend
|
||
|
||
```
|
||
index.php (HTML)
|
||
├── css/style.css
|
||
└── js/app.js
|
||
├── Fetch API (AJAX)
|
||
└── REST API Endpoints
|
||
├── api/repos.php
|
||
├── api/sync.php
|
||
├── api/rollback.php
|
||
└── api/log.php
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 Test-Checklist
|
||
|
||
- [ ] Repository hinzufügen funktioniert
|
||
- [ ] Initial Clone erfolgreich
|
||
- [ ] Webhook empfängt Push-Events
|
||
- [ ] Signatur-Verifizierung funktioniert
|
||
- [ ] Manueller Sync funktioniert
|
||
- [ ] Merge-Konflikte werden erkannt
|
||
- [ ] Rollback erstellt Revert-Commit
|
||
- [ ] Logs werden korrekt geschrieben
|
||
- [ ] Dashboard zeigt Status korrekt
|
||
- [ ] Repository löschen funktioniert
|
||
- [ ] .htaccess blockiert /data/ Zugriff
|
||
- [ ] .htaccess blockiert /src/ Zugriff
|
||
|
||
---
|
||
|
||
## 📚 Erweiterungsmöglichkeiten
|
||
|
||
### Mögliche Features
|
||
|
||
1. **Multi-User Support**
|
||
- User-Login
|
||
- Rollen-System (Admin, User)
|
||
- Repository-Berechtigungen pro User
|
||
|
||
2. **E-Mail Benachrichtigungen**
|
||
- Bei erfolgreicher Sync
|
||
- Bei Fehlern/Konflikten
|
||
- Tägliche Zusammenfassung
|
||
|
||
3. **Deployment Scripts**
|
||
- Post-Sync Hooks (z.B. `npm install`, `composer install`)
|
||
- Custom Shell-Befehle
|
||
- Build-Prozesse
|
||
|
||
4. **Advanced Git Features**
|
||
- Submodules Support
|
||
- Tag/Release Tracking
|
||
- Multi-Branch Sync
|
||
|
||
5. **Monitoring & Alerts**
|
||
- Prometheus Metrics
|
||
- Grafana Dashboard
|
||
- Slack/Discord Webhooks
|
||
|
||
6. **API Authentication**
|
||
- API Keys
|
||
- JWT Tokens
|
||
- Rate Limiting
|
||
|
||
7. **Backup System**
|
||
- Automatische Backups vor Sync
|
||
- Snapshot-Verwaltung
|
||
- Restore-Funktion
|
||
|
||
---
|
||
|
||
**Version**: 1.0.0
|
||
**Erstellt**: 2025-12-06
|
||
**Autor**: Claude Code
|