# GitHub, GitLab oder Bitbucket für Deployments verbinden

> Verbinde GitHub, GitLab (auch self-hosted) oder Bitbucket mit Vimonto Deploy, wähle Repositories, nutze read-only Deploy Keys und deploye bei jedem Push.

Git-Verbindungen verknüpfen deine Git-Accounts mit deiner Organisation, damit Sites aus deinen Repositories deployen können. Vimonto Deploy unterstützt **GitHub**, **GitLab** (gitlab.com), **GitLab (self-hosted)** und **Bitbucket**. Mit einer Verbindung wählst du beim [Anlegen einer Site](https://ops.vimonto.com/docs/de/sites/create-a-site) ein Repository und einen Branch aus einer Liste, und Vimonto Deploy richtet das Repository für dich ein: einen read-only Deploy Key, damit der Server es klonen kann, und einen Push-Webhook, damit jeder Push ein [Deployment](https://ops.vimonto.com/docs/de/sites/deployments) starten kann.

GitHub, GitLab und Bitbucket verbindest du per OAuth (ein Klick, Anmeldung beim Git-Host), ein selbst gehostetes GitLab mit einem Personal Access Token. Du kannst mehrere Accounts verbinden, auch vom selben Dienst. Sie stehen im Abschnitt **Git** unter **Einstellungen** → [Integrationen](https://ops.vimonto.com/docs/de/connections/integrations).

![Der Abschnitt Git mit den verbundenen Accounts bei GitHub, GitLab und Bitbucket](https://ops.vimonto.com/docs-media/de/source-control.webp?v=161e760d "Einstellungen → Integrationen → Git")

## Wer kann einen Git-Account verbinden?

Jedes Mitglied sieht die verbundenen Accounts. Zum Verbinden, Testen, Umbenennen, Neu verbinden und Trennen brauchst du die Rolle **Owner** oder **Administrator**. Ist ein Account verbunden, kann ihn jedes Mitglied, das Sites verwalten darf, für seine Sites nutzen. Verbinden, Umbenennen und Trennen werden im [Audit-Log](https://ops.vimonto.com/docs/de/organization/audit-log) festgehalten, ohne die Tokens.

## GitHub, GitLab oder Bitbucket verbinden

1. Öffne **Einstellungen** → **Integrationen**.
2. Wähle unter **Integration hinzufügen** auf der Karte **GitHub**, **GitLab** oder **Bitbucket** die Option **Verbinden**.
3. Melde dich beim Git-Host an und bestätige den Zugriff.
4. Du kommst zurück zu **Integrationen** mit der Meldung, dass der Account verbunden ist. Die Verbindung wird nach dem Dienst und deinem Benutzernamen dort benannt, zum Beispiel `GitHub (octocat)`.

Verbindest du denselben Account ein zweites Mal, aktualisiert Vimonto Deploy die bestehende Verbindung, statt eine doppelte anzulegen.

> [!NOTE]
> Ein Git-Host zeigt **Demnächst verfügbar**, bis ein Plattform-Administrator seine OAuth-App registriert hat (einmal für die ganze Plattform, unter **Verwaltung** → **Integrationen**). Administratoren sehen auf der Karte stattdessen **Einrichten**.

### Welchen Zugriff fordert Vimonto Deploy an?

| Dienst | Angeforderter Zugriff | Wozu |
| --- | --- | --- |
| GitHub | `repo`, `admin:repo_hook`, `read:user`, `read:org` | Deine Repositories lesen (auch private und die deiner GitHub-Organisationen), Deploy Keys und Push-Webhooks hinzufügen |
| GitLab | `api` | Deine Projekte lesen, Deploy Keys und Push-Webhooks hinzufügen |
| Bitbucket | Account: Read, Repositories: Admin, Webhooks: Read and write | Deine Repositories lesen, Deploy Keys und Push-Webhooks hinzufügen |

Per OAuth bekommt Vimonto Deploy Zugriff auf alle Repositories, die der Account sehen kann. Willst du das einschränken? Nutze dann eine **Eigene Git-URL** mit dem eigenen Deploy Key der Site und füge diesen Schlüssel selbst zu dem einen Repository hinzu.

## Ein selbst gehostetes GitLab verbinden

1. Öffne in deinem GitLab **Preferences** → **Access tokens** → **Add new token**.
2. Wähle den Scope `api` und ein Ablaufdatum, das zu deinen Richtlinien passt.
3. Wähle in Vimonto Deploy unter **Integration hinzufügen** auf der Karte **GitLab (self-hosted)** die Option **Verbinden**.
4. Gib die **Adresse deines GitLab** (zum Beispiel `https://gitlab.company.com`) und das **Personal Access Token** ein.
5. Wähle **Prüfen und verbinden**.

Vimonto Deploy prüft das Token sofort, indem es GitLab fragt, wem es gehört. Die Adresse muss HTTPS verwenden. Dein GitLab muss für Vimonto Deploy (für die API) und für deine Server (zum Klonen) erreichbar sein.

> [!WARNING]
> Ein Personal Access Token funktioniert ab seinem Ablaufdatum nicht mehr. Bereits verknüpfte Sites deployen weiter, denn der Server klont mit dem Deploy Key der Site und Pushes kommen über den Webhook an. Vimonto Deploy kann dann aber deine Projekte nicht mehr auflisten und keine Deploy Keys und Webhooks mehr hinzufügen oder entfernen. Wähle vor oder nach dem Ablaufdatum im Menü (⋯) der Verbindung **Token aktualisieren**, füge ein neues Token desselben GitLab-Accounts ein und wähle **Prüfen und speichern**. Die Verbindung und die Sites, die sie nutzen, bleiben, wie sie sind.

## Ein Repository für eine Site wählen

Wenn du [eine Site anlegst](https://ops.vimonto.com/docs/de/sites/create-a-site), wähle unter **Quellcode** den verbundenen Account. Grenze die Liste bei Bedarf mit **Organisation** ein und wähle dann das **Repository** und seinen Branch. Die Liste beginnt mit den 100 Repositories, in denen der Account zuletzt aktiv war. Tippe ins Suchfeld, um beim Git-Host in allen Repositories zu suchen, auf die der Account Zugriff hat; was gefunden wird, kommt zur Liste hinzu. Du kannst auch jedes Repository über eine **Eigene Git-URL** nutzen. Das Repository einer Site änderst du später auf ihrer Seite **Deployments**.

## Was passiert, wenn eine Site eine Verbindung nutzt?

Wenn du eine Site mit einem Repository aus einem verbundenen Account anlegst oder später das Repository einer Site änderst, führt Vimonto Deploy eine Aufgabe aus, die das Repository verknüpft:

1. **Deploy Key.** Standardmäßig bekommt jede Site ein eigenes SSH-Schlüsselpaar (die Option **Eigener Deploy Key für …** beim Anlegen einer Site). Der öffentliche Schlüssel wird beim Git-Host als **read-only** Deploy Key zum Repository hinzugefügt, benannt nach der Domain und dem Server der Site. Der private Schlüssel kommt auf den Server. So kann der Server klonen und pullen, aber nie pushen.
2. **Push-Webhook.** Für ein Repository aus einem verbundenen Account ist **Bei jedem Push deployen** (Quick Deploy) aktiv. Vimonto Deploy fügt dem Repository also einen Webhook hinzu, der jeden Push an die Deploy-URL der Site sendet. Pushes auf den Branch der Site starten dann ein Deployment. Schaltest du Quick Deploy auf der Seite **Deployments** der Site aus, wird der Webhook wieder entfernt. Lehnt der Git-Host den Webhook ab, wird Quick Deploy ausgeschaltet und die Aufgabe nennt den Grund; die Site deployt weiterhin, wenn du ein Deployment startest.
3. **Erstes Deployment.** Bei einer neuen Site startet das erste Deployment, sobald das Repository verknüpft ist.
4. **Aufräumen.** Wechselst du eine Site auf ein anderes Repository oder eine andere Verbindung oder löschst du die Site, werden der alte Deploy Key und der Webhook beim Git-Host entfernt. Klappt das nicht, etwa weil der Zugriff der alten Verbindung abgelaufen ist, steht es in der Aufgabe, und du entfernst sie selbst beim Git-Host. Bei einem Wechsel bekommt die Site dann einen neuen Deploy Key, damit das neue Repository den alten nicht ablehnt.

Ohne eigenen Deploy Key klont eine Site mit dem Schlüssel des Servers. Diesen Schlüssel findest du unter **Öffentlicher Schlüssel des Servers** in der Übersicht des Servers. Füge ihn selbst bei deinem Git-Host hinzu.

> [!NOTE]
> Auf GitHub kann ein Deploy Key nur von einem Repository verwendet werden. Lehnt GitHub den Schlüssel der Site ab, weil er noch bei einem anderen Repository liegt, gibt Vimonto Deploy der Site einen neuen Deploy Key und fügt diesen hinzu. Entferne den alten Schlüssel selbst beim anderen Repository.

## Token-Erneuerung

Manche Git-Hosts geben Access Tokens aus, die nach ein paar Stunden ablaufen (GitLab und Bitbucket immer, GitHub je nach App). Vimonto Deploy speichert das Refresh Token und holt sich selbst ein neues Access Token, kurz bevor eine Anfrage es braucht. Dafür musst du dich nicht neu verbinden.

Schlägt die Erneuerung fehl, weil der Zugriff beim Git-Host widerrufen oder der Account entfernt wurde, schlagen Anfragen mit einer Meldung wie „Die Verbindung zu GitHub ist abgelaufen. Verbinde dich erneut.“ fehl. Wähle im Menü der Verbindung **Neu verbinden**, um dich erneut anzumelden. Deine Sites nutzen weiter dieselbe Verbindung.

## Eine Verbindung testen, umbenennen und neu verbinden

Jede Verbindung zeigt **Läuft**, wenn ihre letzte Prüfung erfolgreich war, sonst **Neu verbinden**. Im Menü (⋯) neben einer Verbindung kannst du:

- **Verbindung testen**: fragt den Git-Host, zu welchem Account das Token gehört, und zeigt „Angemeldet als …“.
- **Neu verbinden**: meldet dich erneut per OAuth an und erneuert die Tokens (GitHub, GitLab und Bitbucket).
- **Token aktualisieren**: ersetzt das Personal Access Token einer Verbindung zu einem selbst gehosteten GitLab (nur GitLab (self-hosted)). Das neue Token muss zum selben GitLab-Account gehören.
- **Umbenennen**: ändert den Namen, der in Vimonto Deploy angezeigt wird.
- **Trennen**: entfernt die Verbindung.

## Einen Git-Account trennen

Wähle im Menü **Trennen** und bestätige. Das Trennen hält keine Site vom Deployen ab. Was aufhört, ist alles, was über den Account läuft: Du kannst keine Repositories mehr daraus wählen, und Vimonto Deploy kann bei seinen Repositories keine Deploy Keys und Webhooks mehr hinzufügen oder entfernen. Sites, die über ihn verknüpft waren, behalten ihre Repository-Adresse, ihren Deploy Key und ihren Webhook, klonen also weiter, und Pushes starten weiterhin Deployments; auf ihrer Seite **Deployments** zeigen sie jetzt eine **Eigene Git-URL**. Löschst du eine solche Site, entferne ihren Deploy Key und Webhook selbst beim Git-Host.

Vimonto Deploy widerruft seinen Zugriff beim Git-Host nicht. Entferne dazu auch die autorisierte OAuth-App (oder lösche das Access Token) bei GitHub, GitLab oder Bitbucket.

## Häufige Fragen

### Brauche ich eine Git-Verbindung, um zu deployen?

Nein. Du kannst auch von einer **Eigene Git-URL** deployen: per SSH (`git@…`) für private Repositories, mit dem Deploy Key der Site, den du selbst zum Repository hinzufügst, oder per HTTPS für öffentliche. Deployments startest du dann selbst oder aus deiner CI mit der Deploy-URL der Site. Siehe [Deployments](https://ops.vimonto.com/docs/de/sites/deployments).

### Kann Vimonto Deploy in mein Repository pushen?

Nein. Deploy Keys werden read-only hinzugefügt. Ein Server kann also klonen und pullen, aber nicht pushen.

### Sieht Vimonto Deploy alle meine Repositories?

Per OAuth kann es jedes Repository lesen, das der verbundene Account lesen kann. Ändern wird es nur die Repositories, die du mit einer Site verknüpfst (ein Deploy Key und, mit Quick Deploy, ein Webhook). Für engeren Zugriff verbindest du einen separaten Git-Account, der nur Zugriff auf die Repositories hat, die du deployst, oder du nutzt eine eigene Git-URL.

### Kann ich GitHub-Organisationen nutzen?

Ja. Die Repository-Liste enthält die Repositories aus deinem Account und aus den GitHub-Organisationen, in denen du Mitglied bist, soweit die Organisation die OAuth-App zulässt.

### Was passiert mit verknüpften Repositories, wenn ich einen Server übertrage?

Die Verbindungen bleiben bei deiner Organisation. Die Sites auf einem [übertragenen Server](https://ops.vimonto.com/docs/de/servers/transfer-a-server) verlieren ihre Verknüpfung mit der Verbindung, und Quick Deploy wird ausgeschaltet; sie deployen weiter von ihrer Repository-Adresse mit ihrem eigenen Deploy Key. Die neue Organisation kann sie auf der Seite **Deployments** jeder Site mit einer ihrer eigenen Verbindungen verknüpfen.