# Bereitstellen einer Website über Git

Source: https://support.kapsulehost.com/de-de/site-git-deploy

Git Deploy verbindet ein Repository mit einer Website, sodass jeder Push auf den gewählten Branch den Code klont, Ihren Build ausführt und das Ergebnis veröffentlicht. Diese Anleitung behandelt die Erstverbindung, die beiden Schritte auf Repository-Seite, die das Setup abschließen, das Auslesen des Bereitstellungsverlaufs und die Buildpack-Erkennung, die bestimmt, wie eine Node.js-App gebaut wird.

## Wo Sie Git Deploy Finden

Öffnen Sie **Websites**, klicken Sie auf die Website, öffnen Sie die Gruppe **Environment** im linken Menü der Website, und wählen Sie **Git-Deploy**. Zwei verwandte Seiten befinden sich in der Nähe:

- **Deployments**, der vollständige Bereitstellungsverlauf für diese Website, in derselben Gruppe **Environment**.
- **Buildpack**, die erkannte Build-Strategie, bei Node.js-Websites, in der Gruppe **Apps**.

Die Seite Git Deploy beschreibt sich selbst unmissverständlich: Verbinden Sie ein Repository, und jeder Push auf Ihren konfigurierten Branch löst einen Build und ein Deployment aus.

![Die Git-Deploy-Seite für eine Website in KPanel, auf der ein Repository verbunden ist](https://support.kapsulehost.com/help/screenshots/site-git-deploy.4716f1a9.webp)

## Ein Repository Verbinden

1. Wählen Sie Ihren **Provider**: GitHub, GitLab oder Bitbucket.
2. Geben Sie die **Repository-URL** ein. Die SSH-Form ist die gewünschte, zum Beispiel `git@github.com:user/repo.git`.
3. Legen Sie den **Branch** fest, von dem aus bereitgestellt werden soll. Das Feld beginnt bei `main`.
4. Optional können Sie einen **Build-Befehl** festlegen, zum Beispiel `npm run build`.
5. Optional können Sie ein **Ausgabeverzeichnis** festlegen, zum Beispiel `dist`, `public` oder `.` für ein Repository, das bereits gebaut ist.
6. Klicken Sie auf **Repository verbinden**.

Lassen Sie Build-Befehl und Ausgabeverzeichnis leer, wenn Ihr Repository bereits so, wie es ist, bereitstellbar ist, was bei einer einfachen PHP- oder statischen Website der Regelfall ist.

### Erweiterte Skripte

Durch Aufklappen von **Erweitert** erscheinen zwei zusätzliche Felder:

- **Pre-Deploy-Skript**, das vor dem Build ausgeführt wird.
- **Post-Deploy-Skript**, das nach dem Deployment ausgeführt wird.

Nutzen Sie den Post-Deploy-Hook für Dinge, die geschehen müssen, sobald der neue Code vorhanden ist: das Leeren eines Anwendungs-Caches, das Ausführen einer Datenbankmigration, das Neustarten eines Workers.

### Automatisches Deployment Bei Push

Der Schalter am unteren Rand der Karte steuert, ob Pushes überhaupt ein Deployment auslösen. Ist er aktiviert, löst jeder Push auf den konfigurierten Branch ein Deployment aus. Ist er deaktiviert, laufen Deployments nur, wenn Sie sie manuell über **Jetzt bereitstellen** auslösen.

> **Tip:** Schalten Sie das automatische Deployment während eines Code-Freezes oder eines Vorfalls lieber ab, statt das Repository zu trennen. Durch das Trennen werden der Deploy-Schlüssel und das Webhook-Secret verworfen, sodass Sie anschließend beide Schritte auf Repository-Seite erneut durchführen müssen.

## Das Setup In Ihrem Repository Abschliessen

Das Verbinden des Repositorys in KPanel ist nur der erste von drei Schritten. Solange noch kein Deployment gelaufen ist, zeigt die Seite ein Banner mit der Aufschrift **Setup abschließen: 2 Schritte verbleibend** mit allem, was Sie benötigen.

### Schritt 2: Deploy-Schlüssel Hinzufügen

KapsuleHost benötigt Lesezugriff, um Ihr Repository zu klonen. Das Banner zeigt einen öffentlichen Schlüssel mit einer Schaltfläche **Schlüssel kopieren**.

Fügen Sie ihn in die Deploy-Schlüssel Ihres Repositorys ein. Für GitHub bietet das Banner die Abkürzung **Zu GitHub hinzufügen** direkt zur passenden Einstellungsseite. Lesezugriff genügt, gewähren Sie keinen Schreibzugriff.

### Schritt 3: Webhook Hinzufügen

Der Webhook teilt KapsuleHost mit, dass ein Push stattgefunden hat. Das Banner liefert Ihnen drei Werte:

| Feld | Wert |
|---|---|
| Payload-URL | Eine URL, die auf `/api/git-deploy/webhook/` plus die ID dieser Website endet |
| Secret | Ein generiertes Signatur-Secret, verborgen, bis Sie auf das Augensymbol klicken |
| Content-Type | `application/json` |

Kopieren Sie jeden Wert in die Webhook-Einstellungen Ihres Repositorys. Für GitHub gibt es die Abkürzung **Webhook zu GitHub hinzufügen**. Stellen Sie den Content-Type auf JSON, nicht auf den formularkodierten Standard, sonst lässt sich die Payload nicht parsen.

> **Warning:** Behandeln Sie das Webhook-Secret wie ein Passwort. Wer es besitzt, zusammen mit der Payload-URL, kann ein Deployment Ihrer Website auslösen. Beide Werte werden nur Personen angezeigt, die die Website bereits verwalten dürfen, und das Secret bleibt hinter dem Augensymbol verborgen, bis Sie es anfordern.

## Manuell Bereitstellen

Klicken Sie auf der Git-Deploy-Seite auf **Jetzt bereitstellen**, um den aktuellen Stand des konfigurierten Branches zu bauen und bereitzustellen, ohne einen Commit zu pushen. Dies funktioniert unabhängig davon, ob das automatische Deployment aktiviert ist, und macht die Funktion zum richtigen Werkzeug während eines Freezes: Pushes werden ignoriert, aber Sie können den Fix trotzdem ausliefern.

## Den Bereitstellungsverlauf Lesen

Öffnen Sie **Environment**, dann **Deployments**. Die Seite trägt den Titel **Bereitstellungsverlauf** und listet jedes durch Webhook oder manuell ausgelöste Deployment auf, neueste zuerst.

Jede Zeile enthält:

- Ein Statussymbol und die kurze Commit-SHA, mit dem Branch als Pille.
- Die Commit-Nachricht, oder **Manuelles Deployment**, falls keine Commit-Nachricht vorhanden war.
- Den Autor, wie lange es her ist, wie lange es gedauert hat, und was es ausgelöst hat.
- Eine Status-Pille.

Die Status sind **pending**, **building**, **deploying**, **success** und **failed**. Solange etwas läuft, aktualisiert sich die Seite alle fünf Sekunden selbst und zeigt unter der Tabelle den Hinweis **Refreshing automatically**, sodass Sie sie geöffnet lassen und ein Deployment live mitverfolgen können.

### Wenn Ein Deployment Fehlschlägt

Eine fehlgeschlagene Zeile erhält rechts eine Schaltfläche **Error**. Klicken Sie darauf, um die erfasste Fehlerausgabe inline aufzuklappen, ohne die Seite zu verlassen. Diese Ausgabe ist der eigene Fehlertext des Builds, daher nennt er meist die Datei oder den Befehl, der fehlgeschlagen ist.

Gehen Sie in dieser Reihenfolge vor: Fehler lesen, denselben Build-Befehl lokal reproduzieren, beheben, pushen. Wenn der Build lokal funktioniert, hier aber nicht, liegt der Unterschied fast immer an der Umgebung, etwa einer Abhängigkeit, die auf Ihrem Rechner global installiert ist, oder einer Datei, die sich in Ihrem Arbeitsverzeichnis befindet, aber nicht committet wurde.

## Buildpack-Erkennung

Bei Node.js-Websites zeigt die Seite **Buildpack** in der Gruppe **Apps**, wie KapsuleHost entschieden hat, Ihre App zu bauen. Die Erkennung läuft über die Dateien im Wurzelverzeichnis Ihres Repositorys, und der erste Treffer gewinnt:

| Erkannt | Auslöser |
|---|---|
| Individuelles Buildpack | `kapsule.config.yaml` oder `kapsule.config.yml` im Wurzelverzeichnis |
| Dockerfile-Buildpack | `Dockerfile` im Wurzelverzeichnis |
| Node.js | `package.json` mit einem `start`-, `build`- oder `dev`-Skript |
| Python | `requirements.txt` oder `pyproject.toml` |
| PHP | `composer.json` |
| Statisch | `index.html` im Wurzelverzeichnis |

Trifft nichts zu, meldet die Seite dies und listet die unterstützten Auslöser auf. Fügen Sie ein `Dockerfile` oder ein `kapsule.config.yaml` hinzu, um die Kontrolle über den Build ausdrücklich zu übernehmen.

### Einen Build Ausführen

Klicken Sie auf **Build ausführen**, um einen Build einzureihen. Die Seite fragt alle drei Sekunden ab, während ein Lauf aktiv ist, und die Tabelle **Letzte Builds** zeigt die letzten Läufe mit Startzeit, Typ, Status, Dauer und resultierender Image-Referenz. Klicken Sie auf eine Zeile, um das Ende des Logs zu sehen.

Es kann immer nur ein Build gleichzeitig laufen. Das Auslösen eines zweiten, während einer eingereiht ist oder läuft, wird mit **Ein Build ist bereits in Bearbeitung** abgelehnt, was Absicht ist: Zwei Builds, die gleichzeitig dieselbe Ausgabe schreiben, sind der Weg zu einer halb bereitgestellten Website.

## Trennen

Klicken Sie auf **Disconnect** und bestätigen Sie. Die Bestätigung ist eindeutig hinsichtlich der Auswirkungen: Die Git-Deploy-Konfiguration und der Deploy-Schlüssel werden entfernt, und Ihre Website-Dateien sind nicht betroffen. Die Website liefert weiterhin das zuletzt bereitgestellte Ergebnis aus.

Räumen Sie anschließend auf, indem Sie den Deploy-Schlüssel und den Webhook in Ihren Repository-Einstellungen löschen. Sie funktionieren danach einfach nicht mehr, aber verwaiste Einträge erschweren die nächste Prüfung.

## Fehlerbehebung

**Pushes lösen nichts aus.** Prüfen Sie zuerst den Schalter für automatisches Deployment, dann den Webhook in Ihrem Repository. Die meisten Anbieter zeigen die letzten Zustellungen und deren Antwortcodes, was Ihnen sofort verrät, ob die Anfrage Ihr Repository überhaupt verlassen hat.

**Das Klonen schlägt fehl.** Der Deploy-Schlüssel fehlt, wurde mit einem Zeilenumbruch eingefügt oder wurde dem falschen Repository hinzugefügt. Kopieren Sie ihn erneut über die Schaltfläche **Schlüssel kopieren**, statt den Text von Hand zu markieren.

**Das Deployment ist erfolgreich, aber die Website ändert sich nicht.** Das Ausgabeverzeichnis ist vermutlich falsch. Wenn Ihr Build nach `dist` schreibt und das Ausgabeverzeichnis leer ist, erreichen die gebauten Dateien nie die ausgelieferte Wurzel.

**Alles zeigt pending und bewegt sich nie.** Das Deployment wurde eingereiht, aber nie aufgenommen. Lösen Sie ein manuelles **Jetzt bereitstellen** aus und prüfen Sie die Seite Deploys auf eine Fehlerzeile.

## Wie Es Weitergeht

- [Vorschau-Deployments für Pull Requests](https://support.kapsulehost.com/de-de/site-preview) fügt diesem Setup eine URL pro Pull Request hinzu.
- [App-Geheimnisse für eine Website Speichern](https://support.kapsulehost.com/de-de/site-secrets) für die Zugangsdaten, die Ihr Build und Ihre Laufzeitumgebung benötigen.
- [Aktivitätsprotokoll der Website](https://support.kapsulehost.com/de-de/site-activity-log) zeichnet hier vorgenommene Konfigurationsänderungen auf.