# GitLab-Gruppe mit der Entwicklung verbinden

> **Zielgruppe & Rolle**
>
> **Rolle**: Administration | **Voraussetzung**: Recht `tenant:scm:admin` und Owner-Rechte in der
> GitLab-Gruppe, um ein Dienstkonto anzulegen

# GitLab-Gruppe mit der Entwicklung verbinden

Mit der GitLab-Anbindung verknüpfen Vorgänge und Projekte der Entwicklung Branches und Merge Requests Ihrer GitLab-Gruppe,
genau wie bei GitHub. Beide Anbieter können im selben Mandanten und sogar im selben Projekt nebeneinander genutzt werden.
Die Anbindung arbeitet ohne Mitarbeiterkonto im Hintergrund: ConnectCloud liest mit dem Token eines **Dienstkontos**, damit
nichts davon abhängt, ob eine Person im Unternehmen bleibt.

## Einrichten auf gitlab.com (Free)

1. **Eigenes GitLab-Konto verknüpfen.** Einstellungen › Persönlich › **GitLab-Konto** › verknüpfen. Das ist der Nachweis,
   dass Sie Zugriff auf die Gruppe haben; Sie müssen in der Gruppe mindestens **Maintainer** sein. Schreibende Aktionen
   (Merge Request öffnen, mergen) laufen später immer mit Ihrem eigenen Konto.
2. **Dienstkonto anlegen.** In GitLab als Owner der obersten Gruppe: Gruppe › Einstellungen › Service accounts › neues Dienstkonto
   (belegt im Free-Tarif **keinen** Platz). Fügen Sie es der Gruppe als **Maintainer** hinzu.
3. **Token erstellen.** Für das Dienstkonto einen persönlichen Zugriffstoken mit dem Scope **`api`** und einem **Ablaufdatum**
   anlegen. In Premium oder selbst betriebenem GitLab funktioniert stattdessen ein Gruppen-Zugriffstoken (Maintainer, `api`).
4. **Verbinden.** Einstellungen › Integrationen › **GitLab**: Gruppenpfad (z. B. `mbcom`) und Token eintragen. ConnectCloud
   prüft Token, Scope und Rolle, liest die Projekte der Gruppe samt Untergruppen und richtet die Webhooks ein.

> [!IMPORTANT] Ein Dienstkonto je Umgebung
> Verbinden mehrere Umgebungen (z. B. lokal, Beta, Produktion) dieselbe Gruppe, legen Sie **für jede Umgebung ein eigenes
> Dienstkonto mit eigenem Token** an. Jede Umgebung erneuert nur ihren Token und ändert nur Webhooks mit ihrer eigenen Adresse.
> Webhooks anderer Umgebungen bleiben unberührt.

Eine Gruppe lässt sich nur mit einem Mandanten verbinden, und nicht, wenn eine übergeordnete oder untergeordnete Gruppe schon
mit einem anderen Mandanten verbunden ist.

## Webhooks

Im Free-Tarif legt ConnectCloud **einen Webhook je Projekt** an (Gruppen-Webhooks gibt es erst in Premium; dort wird
automatisch einer für die ganze Gruppe genutzt). Neue Projekte erkennt der regelmäßige Abgleich oder die Schaltfläche
**Synchronisieren**; fehlende Webhooks legt eine stündliche Prüfung nach, bei vielen Projekten nach und nach.

## Warnungen und Status

- **Token läuft bald ab:** Die Seite zeigt das Ablaufdatum immer an. ConnectCloud erneuert den Token selbst, sobald er in
  weniger als sieben Tagen abläuft. Schlägt das fehl, tragen Sie rechtzeitig einen neuen Token ein.
- **Anmeldung erforderlich (`reauth_required`):** GitLab hat den Token abgelehnt (abgelaufen, widerrufen) oder die Gruppe ist
  nicht mehr erreichbar (das Dienstkonto wurde entfernt). Solange das so ist, gleicht ConnectCloud nichts ab. Tragen Sie einen
  neuen Token ein (**Token ersetzen**); die Verbindung und alle Verknüpfungen bleiben erhalten.
- **Trennen:** entfernt die von ConnectCloud angelegten Webhooks (soweit erreichbar), die Verbindung und die Verknüpfungen von
  Vorgängen mit Branches und Merge Requests dieser Gruppe. Dienstkonto und Token bleiben in GitLab; entfernen Sie sie dort,
  wenn Sie sie nicht mehr brauchen.

## Was GitLab nicht kann (gegenüber GitHub)

| GitHub | GitLab |
|---|---|
| Sicherheitswarnungen (Dependabot, Code Scanning) | nicht angeboten (brauchen Ultimate) |
| Team als Reviewer vorschlagen | nicht angeboten: GitLab-Reviewer sind Personen |
| Codefrequenz, Wochenstatistik je Autor | nicht angeboten; Aktivität und Punch Card aus den Commits der letzten 52 Wochen |
| Workflows | eine Pipeline je Repository (`.gitlab-ci.yml`) |

Wo GitLab etwas nicht kennt, blendet die Oberfläche es aus. Die Wörter folgen dem Anbieter: „Merge Request“ und „Pipeline“ statt
„Pull Request“ und „Workflow“.
