Add GitHub Sync - Automated repository synchronization tool
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.
This commit is contained in:
Claude
@@ -0,0 +1,447 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user