Ai/gitpusher/README.md

GitHub Sync - Automatische Repository-Synchronisation

Eine einfache und sichere Lösung zur automatischen Synchronisation von GitHub-Repositories auf deinem Server mittels Webhooks.

📋 Features

• ✅ Automatische Synchronisation via GitHub Webhooks
• ✅ Mehrere Repositories gleichzeitig verwalten
• ✅ Branch-Auswahl pro Repository
• ✅ Webhook-Sicherheit mit Secret-Verifizierung
• ✅ Manueller Sync über das Dashboard
• ✅ Rollback-Funktion via git revert
• ✅ Konflikt-Erkennung mit Warnungen
• ✅ Log-System für alle Ereignisse
• ✅ Datei-basiert - keine Datenbank erforderlich
• ✅ Responsives Dashboard mit Echtzeit-Updates

🔧 Systemanforderungen

• Server: Ubuntu Server (LXC Container auf Proxmox)
• Webserver: Apache 2.4+
• PHP: 7.4+ (8.0+ empfohlen)
• Git: 2.0+
• Berechtigungen: Root-Zugriff für Installation

📦 Installation

1. Voraussetzungen prüfen

# PHP Version prüfen
php -v

# Git Version prüfen
git --version

# Apache Status prüfen
systemctl status apache2

2. Benötigte PHP-Module installieren

sudo apt update
sudo apt install php php-cli php-json php-mbstring

3. Apache-Konfiguration

Virtual Host erstellen

sudo nano /etc/apache2/sites-available/github-sync.conf

Füge folgende Konfiguration ein:

<VirtualHost *:80>
    ServerName github-sync.deine-domain.de
    DocumentRoot /gitpusher/public

    <Directory /gitpusher/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    # Deny access to data and src directories
    <Directory /gitpusher/data>
        Require all denied
    </Directory>

    <Directory /gitpusher/src>
        Require all denied
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/github-sync-error.log
    CustomLog ${APACHE_LOG_DIR}/github-sync-access.log combined
</VirtualHost>

Site aktivieren

sudo a2ensite github-sync.conf
sudo a2enmod rewrite
sudo systemctl reload apache2

4. Berechtigungen setzen

# Eigentümer auf www-data setzen
sudo chown -R www-data:www-data /gitpusher

# Schreibrechte für data-Verzeichnis
sudo chmod 755 /gitpusher/data
sudo chmod 600 /gitpusher/data/*.json

# Ausführrechte für public-Verzeichnis
sudo chmod 755 /gitpusher/public

5. GitHub Personal Access Token erstellen

1. Gehe zu GitHub → Settings → Developer settings → Personal access tokens
2. Klicke auf "Generate new token (classic)"
3. Name: GitHub Sync Server
4. Wähle Scopes:
   • ✅ repo (Full control of private repositories)
5. Klicke auf "Generate token"
6. Kopiere den Token sofort - er wird nur einmal angezeigt!

6. Token in der Anwendung hinterlegen

Bearbeite /gitpusher/data/secrets.json:

sudo nano /gitpusher/data/secrets.json

Füge deinen GitHub PAT ein:

{
  "github_pat": "ghp_deinTokenHier1234567890",
  "webhook_secrets": {}
}

Speichern mit Ctrl+O, beenden mit Ctrl+X.

🚀 Verwendung

Dashboard öffnen

Öffne deinen Browser und navigiere zu:

http://github-sync.deine-domain.de

Repository hinzufügen

1. Klicke auf "+ Repository hinzufügen"
2. Fülle das Formular aus:
   • Name: Ein aussagekräftiger Name (z.B. "Meine Website")
   • GitHub Repository URL: https://github.com/user/repo.git
   • Branch: z.B. main oder master
   • Ziel-Pfad: z.B. /var/www/meine-website
   • Auto-Sync: Aktiviert für automatische Webhooks
3. Klicke auf "Repository hinzufügen"

Die App klont das Repository automatisch und zeigt dir die Webhook-Konfiguration an.

GitHub Webhook einrichten

1. Gehe zu deinem GitHub Repository → Settings → Webhooks → Add webhook
2. Füge die Informationen aus dem Modal ein:
   • Payload URL: (aus dem Modal kopieren)
   • Content type: application/json
   • Secret: (aus dem Modal kopieren)
   • Events: "Just the push event"
3. Klicke auf "Add webhook"

Ab jetzt wird bei jedem Push automatisch synchronisiert!

Manueller Sync

Klicke auf den Button "🔄 Manueller Sync" bei einem Repository, um sofort zu synchronisieren.

Rollback durchführen

1. Klicke auf "⏪ Rollback" bei einem Repository
2. Wähle den Commit aus, zu dem du zurückkehren möchtest
3. Bestätige die Aktion

Wichtig: Es wird ein neuer Revert-Commit erstellt, keine Commits werden gelöscht!

Repository entfernen

1. Klicke auf "🗑️ Entfernen"
2. Wähle, ob auch die Dateien gelöscht werden sollen
3. Bestätige die Aktion

📁 Dateistruktur

/gitpusher/
├── public/                     # Web-Root (Apache DocumentRoot)
│   ├── index.php              # Dashboard
│   ├── webhook.php            # Webhook-Endpoint
│   ├── api/
│   │   ├── repos.php          # Repository-Verwaltung
│   │   ├── sync.php           # Manueller Sync
│   │   ├── rollback.php       # Rollback-Funktion
│   │   └── log.php            # Logs abrufen
│   ├── css/
│   │   └── style.css          # Styling
│   └── js/
│       └── app.js             # Frontend-Logik
│
├── data/                       # Daten (nicht web-zugänglich)
│   ├── config.json            # Repository-Konfiguration
│   ├── log.json               # Log-Einträge
│   ├── secrets.json           # GitHub PAT & Webhook Secrets
│   └── .htaccess              # Zugriff verweigern
│
├── src/                        # PHP-Klassen
│   ├── ConfigManager.php      # Konfigurationsverwaltung
│   ├── Logger.php             # Logging
│   ├── GitHandler.php         # Git-Operationen
│   └── .htaccess              # Zugriff verweigern
│
├── .htaccess                   # Hauptkonfiguration
└── README.md                   # Diese Datei

🔒 Sicherheit

Webhook-Signatur-Verifizierung

Alle Webhooks werden mit HMAC SHA-256 signiert und verifiziert. Ohne gültiges Secret werden Requests abgelehnt.

Datei-Berechtigungen

• /gitpusher/data/: Nur von PHP lesbar (600)
• /gitpusher/src/: Nicht web-zugänglich
• .htaccess: Schützt sensitive Verzeichnisse

GitHub PAT

• Wird verschlüsselt in secrets.json gespeichert
• Nur repo-Scope erforderlich
• Kann jederzeit in GitHub widerrufen werden

🐛 Troubleshooting

"Permission denied" beim Clonen

# Stelle sicher, dass www-data Schreibrechte hat
sudo chown -R www-data:www-data /var/www
sudo chmod 755 /var/www

Webhook wird nicht empfangen

1. Prüfe GitHub Webhook Deliveries auf Fehler
2. Überprüfe Apache Error Log:

   sudo tail -f /var/log/apache2/github-sync-error.log
   

3. Teste Webhook manuell:

   curl -X POST http://github-sync.deine-domain.de/webhook.php \
        -H "Content-Type: application/json" \
        -d '{"repository":{"clone_url":"https://github.com/user/repo.git"}}'
   

Merge-Konflikt

Bei Konflikten zeigt das Dashboard eine Warnung. Löse den Konflikt manuell:

cd /var/www/dein-repo
sudo -u www-data git status
# Konflikt manuell lösen
sudo -u www-data git add .
sudo -u www-data git commit -m "Konflikt gelöst"

Logs prüfen

# PHP Error Log
sudo tail -f /var/log/apache2/error.log

# App Logs
cat /gitpusher/data/log.json | jq

📊 API-Endpunkte

GET /api/repos.php

Listet alle Repositories auf

POST /api/repos.php

Fügt neues Repository hinzu

PUT /api/repos.php

Aktualisiert Repository

DELETE /api/repos.php

Löscht Repository

POST /api/sync.php

Führt manuellen Sync durch

GET /api/rollback.php

Listet Commits für Rollback

POST /api/rollback.php

Führt Rollback durch

GET /api/log.php

Ruft Logs ab

POST /webhook.php

Empfängt GitHub Webhooks

🔄 Updates

Um das System zu aktualisieren:

1. Backup erstellen:

   sudo cp -r /gitpusher/data /gitpusher/data.backup
   

2. Neue Dateien deployen

3. Berechtigungen prüfen:

   sudo chown -R www-data:www-data /gitpusher
   

📝 Lizenz

Dieses Projekt ist für den persönlichen und kommerziellen Gebrauch frei verfügbar.

🙋 Support

Bei Fragen oder Problemen:

1. Prüfe die Logs im Dashboard
2. Prüfe Apache Error Logs
3. Prüfe GitHub Webhook Delivery Logs

---

Erstellt mit ❤️ für einfache GitHub-Synchronisation