Git-Hosting

Git-Integrationen entscheiden, aus welchen Repositories Opfield bauen darf. Ein bestimmter Commit lässt sich über seinen Build bis zu einem unveränderlichen Artefakt und dem Release verfolgen, das ihn ausführt.

Konfigurieren Sie Quellintegrationen unter Settings > Integrations. Unterstützte Anbieter sind GitLab, GitHub und generisches Git. GitHub- und generische Git-Connectoren sind in jedem Tarif verfügbar; die GitLab-Integration, einschließlich der Erkennung von GitLab-Registries, erfordert Personal oder höher. GitLab-Connectoren, die vor 2.11 in Community erstellt wurden, bleiben erhalten, können aber erst geöffnet werden, wenn ein Schlüssel ab Personal aktiv ist. Builds aus Git-Quellen erfordern Business oder Enterprise. Für den Zugriff auf ein entferntes Betriebssystem verwenden Sie die separate Anleitung SSH-Verbindungen.

Verwenden Sie eine eigene Maschinen- oder Anwendungsidentität mit nur lesendem Repository-Zugriff, sofern ein Ablauf nicht ausdrücklich mehr erfordert. Beschränken Sie erlaubte Repositories und Hosts. Prüfen Sie Echtheit von Webhooks, Branch-Auswahl, Auflösung von Commits und Rotation von Zugangsdaten.

Repository-URLs dürfen keine eingebetteten Zugangsdaten enthalten. Die Prüfung von SSH-Host-Schlüsseln und HTTPS-Zertifikaten muss sicher fehlschlagen (fail closed). Entfernen Sie eine Integration erst, nachdem abhängige Docker-, Compose- und Pages-Quellen ermittelt und migriert wurden.

Integrationstypen

• GitLab: Erkennung von Projekten und Gruppen, Repository-Operationen, Webhooks, Variablen, CI-bezogene Abläufe und je nach Leistungsumfang optionale Erkennung von Registries.
• GitHub: Erkennung von Repositories und unterstützte Repository- bzw. Actions-Operationen über den konfigurierten Anwendungs- oder Token-Weg.
• Generisches Git: begrenzter authentifizierter Repository-Zugriff, wenn kein Anbieter mit eigener Unterstützung erforderlich ist.

GitLab

1. Verwenden Sie einen eigenen GitLab-Benutzer, der nur Mitglied der benötigten Gruppen bzw. Projekte ist. Öffnen Sie in GitLab das Avatar-Menü, Edit profile > Access > Personal access tokens. Erstellen Sie ein Token (die Oberfläche nennt es möglicherweise Legacy Personal Access Token).
2. Legen Sie Namen und Ablauf fest und wählen Sie dann die Berechtigungen aus der Tabelle. Kopieren Sie das Secret sofort.
3. Geben Sie in der GitLab-Integration von Opfield den Origin der Instanz ein, zum Beispiel https://gitlab.example.com, ohne /api/v4, sowie das Token. Wählen Sie die erlaubten Projekte bzw. Gruppen, statt jedes erkannte Projekt freizugeben.
4. Testen Sie das Token, erkennen Sie ein erlaubtes Projekt und prüfen Sie den Repository- und Branch-Zugriff. Ein GitLab-Deploy-Token ist kein Ersatz für diese API-Identität.

Ablauf	Scopes des GitLab-Tokens
Projekte erkennen und API-Metadaten lesen	read_api
Repository-Quellen für Builds lesen bzw. klonen	read_repository zusammen mit read_api für den Connector mit eigener Unterstützung
Private Registry-Images erkennen bzw. beziehen	Zusätzlich read_registry und die nötige Projektmitgliedschaft
Dateien über die API schreiben, Hooks bzw. Variablen verwalten oder CI-Änderungen vornehmen	api; der Benutzer muss außerdem die erforderliche Projektrolle haben
Über Git per HTTPS pushen	write_repository; das gewährt keinen allgemeinen API-Schreibzugriff

Beginnen Sie für reine Lese-Builds mit read_api + read_repository, nicht mit api. Der breite Scope api ist nur angemessen, wenn Sie die Schreibabläufe aktivieren, die ihn benötigen. Token-Scopes können weder Regeln für geschützte Branches noch fehlende Projektmitgliedschaften außer Kraft setzen. Benutzerspezifische GitLab-Autorisierung für interaktive Werkzeuge bleibt vom gespeicherten System-Token getrennt.

Referenzen: Ein GitLab Personal Access Token erstellen, Scopes von GitLab-Access-Tokens.

GitHub

Wenn Sie einen GitHub-Connector hinzufügen, fragt Opfield, wie er autorisiert werden soll. Wählen Sie für GitHub.com OAuth (Recommended): Opfield zeigt einen Gerätecode, Sie bestätigen ihn bei GitHub, und es wird kein Token in Opfield kopiert. Es fordert repo, workflow, read:org und read:packages an; prüfen Sie den Organisations- und Repository-Zugriff im Zustimmungsbildschirm von GitHub. Wählen Sie für GitHub Enterprise oder zur Verwendung eines Tokens Personal access token:

1. Öffnen Sie bei GitHub Settings > Developer settings > Personal access tokens > Tokens (classic) > Generate new token (classic).
2. Legen Sie einen eigenen Namen und Ablauf fest. Wählen Sie repo für private Repositories oder public_repo, wenn nur öffentliche Repositories benötigt werden. Das sind breite Repository-Berechtigungen, keine reinen Lese-Scopes: Verwenden Sie eine Identität, deren Repository-Zugriff angemessen beschränkt ist.
3. Fügen Sie optionale Berechtigungen nur für den entsprechenden Ablauf unten hinzu. Erzeugen und kopieren Sie das Token. Autorisieren Sie es bei Bedarf für Organisations-SSO.
4. Fügen Sie das Token in der GitHub-Integration von Opfield hinzu, wählen Sie die erlaubten Repositories bzw. Organisationen und testen Sie die Erkennung von Repositories und die vorgesehene Revision.

Zusätzliche Verwendung	Scope des klassischen Tokens
Mitgliedschaft in Organisationen bzw. Teams lesen	read:org
Pakete aus GitHub Packages herunterladen	read:packages
Workflow-Dateien ändern	workflow, zusätzlich zum Repository-Zugriff

Aktuelle Kompatibilitätseinschränkung: Opfield erkennt die Fähigkeiten von GitHub-Tokens anhand klassischer OAuth-Scopes. Ein fein granulares PAT kann sich bei GitHub authentifizieren und von diesem Connector dennoch ohne Repository-Fähigkeiten gemeldet werden. Verwenden Sie es nicht als direkten Ersatz für das obige Rezept. Verbietet die Organisation klassische PATs, verwenden Sie die Option OAuth oder klären Sie die Kompatibilität des Connectors vor dem Verbinden; schwächen Sie nicht die Richtlinie der Organisation. Kein delete_repo- oder Organisationsverwaltungs-Scope ist erforderlich, nur um ein gespeichertes Repository zu bauen.

Referenzen: GitHub Personal Access Tokens verwalten, Bedeutung klassischer OAuth-Scopes.

Generisches Git

1. Erstellen Sie auf dem Git-Server eigene Zugangsdaten, mit denen die ausgewählten Repositories geklont werden können. Beispielsweise kann ein GitLab-Deploy-Token mit read_repository für den Zugriff über Git per HTTPS verwendet werden; es ist kein GitLab-API-Token mit eigener Unterstützung.
2. Wählen Sie in Opfield generisches Git. Geben Sie Git host URL ein, zum Beispiel https://git.example.com, sowie die ausdrücklichen Repositories, zum Beispiel https://git.example.com/team/app.git.
3. Geben Sie Username und Access token getrennt ein. Verwenden Sie bei einem Deploy-Token den Benutzernamen, der mit diesem Token ausgegeben wurde. Betten Sie keinen der beiden Werte in Repository-URLs ein.
4. Führen Sie Test Connection aus und speichern Sie dann. Der Verbindungstest verwendet das erste Repository: Prüfen Sie auch den Zugriff auf jedes andere erlaubte Repository, bevor Sie sich für einen Build darauf verlassen.

Dieser Connector verwendet HTTPS-Zugangsdaten, keinen aus External SSH importierten privaten Schlüssel. Er bietet weder ein universelles Scope-Vokabular für Git-Anbieter noch den vollen API-Funktionsumfang von GitLab bzw. GitHub. Ein erfolgreicher Klon bedeutet keine Berechtigung, Webhooks, Variablen oder CI über eine API zu verwalten.

Sicher konfigurieren

1. Erstellen Sie eine eigene Anbieter- oder Maschinenidentität.
2. Gewähren Sie nur lesenden Repository-Zugriff, sofern kein dokumentierter Ablauf Schreibzugriff benötigt.
3. Beschränken Sie Organisationen, Gruppen, Projekte und Repositories mit dem unterstützten Auswahlmodus des Connectors.
4. Fügen Sie die Integration unter Settings → Integrations hinzu.
5. Prüfen Sie TLS oder die SSH-Host-Identität, bevor Sie Zugangsdaten speichern.
6. Testen Sie die Erkennung von Repositories und den Zugriff auf eine erlaubte Revision.
7. Testen Sie, dass ein Repository oder Host außerhalb des Geltungsbereichs abgewiesen wird.
8. Konfigurieren Sie Echtheit und Zustellung von Webhooks erst, wenn der Leseweg funktioniert.

Repository-Zugriff einschränken

Die Allowlist des Connectors entscheidet, welche Repositories Opfield überhaupt erreichen kann. Scopes der Git-Integration entscheiden, welche Benutzer, Gruppen, API-Tokens und OAuth-Freigaben sie verwenden dürfen. Jeder Git-Scope außer manage kann unterhalb des Connectors eingeschränkt werden:

• GitLab: eine Gruppe, die auch ihre Untergruppen und jedes Projekt darunter umfasst, oder ein einzelnes Projekt. Opfield liest die übergeordneten Gruppen eines Projekts aus GitLab, sodass ein in eine andere Gruppe verschobenes Projekt seiner neuen Gruppe folgt.
• GitHub: ein Owner, der jedes Repository dieser Organisation oder dieses Benutzers umfasst, oder ein einzelnes Repository.
• Generisches Git: nur der Connector.

Die Verwaltung des Connectors – Einstellungen, Tokens, Allowlist, Synchronisation, Test und Löschung – erfordert integrations:<provider>:manage auf dem Connector oder ohne Einschränkung; eine Berechtigung auf eine Gruppe, einen Owner, ein Projekt oder ein Repository erlaubt sie nie.

Am schnellsten vergeben Sie Repository-Zugriff über Add Access > Git repositories im Gruppendialog, in den zusätzlichen Berechtigungen eines Benutzers oder im Dialog für API-Tokens: Wählen Sie den Connector, Every repository oder eine Gruppe, einen Owner oder einzelne Repositories sowie die Zugriffsstufe (Use, Read code oder Edit code and CI), die die passenden Scopes setzt. Um einen einzelnen Scope einzuschränken, öffnen Sie in diesen Dialogen oder in der OAuth- und MCP-Zustimmung unter Review N scopes seine Einschränkung. Markieren Sie einen Connector, um alle seine Repositories abzudecken, oder öffnen Sie unter dem Connector Add groups or projects… bzw. Add owners or repositories…, um beim Anbieter zu suchen und Ziele auszuwählen. Berechtigungen speichern die numerischen IDs des Anbieters, sodass Umbenennungen und Verschiebungen sie nicht beschädigen; ein inzwischen gelöschtes Ziel wird als Unavailable angezeigt und kann weiterhin entfernt werden.

Mit eingeschränkten Berechtigungen:

• Connector-, Projekt- und Repository-Listen, einschließlich der Auswahl der Build-Quelle, zeigen nur, was die Berechtigungen abdecken. Ein Projekt, das in einer Liste fehlt, liegt meist außerhalb der Berechtigung, statt nicht synchronisiert zu sein.
• Jede Repository-Operation prüft das Repository – Dateien, Branches, Commits, Pipelines und Job-Logs, Variablen, Webhooks, Deploy-Tokens, Registry-Einstellungen und Sandbox-Klone –, in der Konsole, der REST API, im AI Workspace und in MCP gleichermaßen. Ein GitLab-Projekt außerhalb der Berechtigung antwortet genau wie ein Projekt, das nicht synchronisiert ist: 404 GITLAB_PROJECT_NOT_FOUND, ohne seinen Pfad, sodass Projekt-IDs nicht ausgeforscht werden können. Bei GitHub und generischem Git, wo der Aufrufer das Repository bereits angibt, liefert eine Ablehnung 403 CONNECTOR_SCOPE_DENIED mit dem erforderlichen Scope.
• Opfield verwendet die Zugangsdaten des Connectors für ein Repository nur, wenn use dieses Repository abdeckt; andernfalls verwendet es die persönlichen Zugangsdaten des Benutzers.
• Schreibvorgänge, Secrets, Sandbox-Klone und die Entscheidung über die Zugangsdaten lesen die Gruppen eines GitLab-Projekts bzw. den Owner eines GitHub-Repositorys frisch beim Anbieter, sodass ein übertragenes Repository danach beurteilt wird, wo es jetzt liegt; einfache Lesevorgänge können einen bis zu fünf Minuten alten zwischengespeicherten Wert verwenden. Synchronisationen von Connectoren und Webhook-Zustellungen von Quellen leeren den Cache.
• Die Suchauswahl bietet nur Ziele innerhalb der Allowlist des Connectors an und ist auf 60 Anfragen pro Minute und Konto begrenzt; darüber hinaus liefert sie 429 SCOPE_TARGET_RATE_LIMITED mit Retry-After.
• API-Tokens und OAuth-Freigaben behalten ihre eigenen Einschränkungen und werden bei jeder Anfrage zusätzlich gegen die aktuellen Berechtigungen des Eigentümers geprüft. Ein auf ein Projekt beschränktes Token funktioniert, solange sein Eigentümer die Gruppe besitzt, die das Projekt enthält, und hört auf zu funktionieren, wenn der Eigentümer diesen Zugriff verliert.

Das genaue Format der Qualifizierer und die Endpunkte der Auswahl finden Sie unter Einschränkungen der Git-Integration.

Lebenszyklus von Quell-Bindings

Wer darf bauen und Ergebnisse ansehen?

Die Erkennung von Repositories und direkte Quelloperationen verwenden Scopes der Anbieterintegration. GitLab, GitHub und generisches Git teilen dieselben Verben: integrations:<provider>:view listet Connectoren auf, :manage konfiguriert, testet und synchronisiert sie, :use verwendet die eigenen Zugangsdaten des Connectors, und :repo:read und :repo:write lesen bzw. ändern Repository-Inhalte. Das Auflisten und Lesen der synchronisierten Projekte von GitLab erfordert integrations:gitlab:view. GitLab-repo:read umfasst Repository-Dateien, CI-Pipelines und Job-Logs sowie Schlüssel von CI/CD-Variablen, niemals Werte; das Ändern von Variablen erfordert repo:write, und das Lesen von Werten der GitHub-Actions-Variablen erfordert integrations:github:repo:write. Die integrierten Gruppen viewer und operator erhalten nur integrations:gitlab:view. Siehe die Scope-Referenz. Jeder dieser Scopes kann auf einen Connector, eine GitLab-Gruppe oder ein GitLab-Projekt bzw. einen GitHub-Owner oder ein GitHub-Repository beschränkt werden; siehe Repository-Zugriff einschränken.

Das Anhängen oder Ändern eines Quell-Bindings erfordert integrations:<provider>:use auf dem Repository, neben den eigenen Berechtigungen des Workloads. use, beschränkt auf genau dieses Projekt oder Repository, genügt; repo:read und persönliche Zugangsdaten des Anbieters sind nicht erforderlich, weil Builds die Zugangsdaten des Connectors verwenden. Die integrierte Gruppe operator kann daher GitLab-Projekte in der Quellauswahl sehen, aber keine Quelle speichern, bis ihr integrations:gitlab:use gegeben wird, vorzugsweise beschränkt auf die Projekte, die sie baut. Die interaktiven GitLab-Werkzeuge im AI Workspace fragen nach der eigenen GitLab-Autorisierung des Benutzers, wenn use das Projekt nicht abdeckt.

Das Starten eines Builds aus einer bereits gespeicherten Quelle ist eine Ressourcenaktion – docker:containers:manage für Container und Deployments, docker:compose:manage für Compose und pages:deploy für Pages – und prüft außerdem erneut das integrations:<provider>:use des Aufrufers auf dem gespeicherten Repository, sodass der Widerruf von use manuelle Neubauten stoppt. repo:read ist weiterhin nicht erforderlich. Opfield prüft außerdem den gespeicherten Connector, das erlaubte Repository und die Zugangsdaten der Quelle.

Automatische Builds über Polling und Webhooks hängen davon ab, wann die Quelle zuletzt gespeichert wurde:

• Vor 2.11 gespeicherte Quellen bauen genau wie bisher automatisch weiter.
• Seitdem erstellte oder erneut gespeicherte Quellen bauen nur automatisch, solange das Konto, das sie zuletzt gespeichert hat, noch integrations:<provider>:use auf dem Repository besitzt und aktiv ist. Andernfalls läuft kein Build: Der Build-Verlauf zeigt einen abgebrochenen Build mit SOURCE_OWNER_ACCESS_REVOKED und der Meldung Build paused: <user> no longer has use on <repo>, einmal pro Commit erfasst, und die Quelle zeigt dieselbe Meldung als ihren Polling- bzw. Webhook-Fehler. Webhook-Zustellungen werden weiterhin angenommen. Automatische Builds werden fortgesetzt, wenn das Konto use zurückerhält oder wenn jemand, der es besitzt, die Quelle erneut speichert.

Vergeben Sie use an die Teams, die Quellen speichern, beschränkt auf ihre Projekte, bevor Sie sich auf automatische Builds verlassen.

Build-Verlauf und Logs erfordern Lesezugriff auf das Ziel: docker:containers:view, docker:compose:view oder pages:view. Ressourcen- und geerbte Ordnereinschränkungen gelten. Seit 2.11 gewährt jeder Aktions-Scope auf demselben Ziel, etwa docker:containers:manage, auch dessen Ansicht. Vergeben Sie keinen kontoweiten Repository- oder Node-Zugriff, um eine fehlende Zielberechtigung zu umgehen. Siehe Berechtigungen.

Gespeicherte Quell-Bindings

Docker-Workloads, Compose-Projekte und Pages-Projekte erstellen ihre eigenen Quell-Bindings. Ein Quell-Binding erfasst die Integration, das Repository, die Revisionsauswahl, die Build-Konfiguration, die Automatisierungsrichtlinie und quellbezogene Build Secrets.

Das Entfernen einer Integration macht abhängige Ressourcen nicht sicher neu baubar. Erfassen Sie zuerst die Abhängigkeiten, deaktivieren Sie automatische Aktionen, migrieren Sie jedes Quell-Binding und prüfen Sie die Ersatzrevision und die Zugangsdaten.

Fahren Sie mit Docker-Git-Builds, Pages-Git-Deployments und Container-Registries fort. Für andere Connector-Typen kehren Sie zu Integrationen zurück.

Fehlerbehebung

Trennen Sie Authentifizierungsfehler, Ablehnung durch die Allowlist, nicht gefundenes Repository, Auflösung der Revision, Webhook-Zustellung, Zulassung durch den Build Worker und Fehler beim Leistungsumfang. Bewahren Sie Request-IDs des Anbieters und den Task-Verlauf von Opfield, ohne Tokens, private Schlüssel, Variablen oder Build Secrets zu protokollieren.

Quellablauf für die Produktion

Legen Sie die Produktionsquelle auf eine geprüfte Branch-Richtlinie und einen genau aufgelösten Commit fest. Ein Branch-Name ist eine Auswahleingabe; der Commit-Digest ist der unveränderliche Beleg dafür, was gebaut wurde. Bestätigen Sie Anwendungsverzeichnis, Paketmanager, Build-Skript, Artefaktverzeichnis, Laufzeitplattform und Veröffentlichungs- bzw. Deployment-Richtlinie, bevor Sie automatische Aktionen aktivieren. Halten Sie Build Secrets getrennt von gewöhnlichen Laufzeitvariablen und stellen Sie nur die Werte bereit, die in der Build-Phase benötigt werden.

Prüfen Sie bei Pages und verwalteten Git-Builds die vollständige Kette: Anbieterzugriff, Erkennung des Repositorys, Auflösung des Commits, Zulassung durch den Build Worker, Abruf der Abhängigkeiten, Erstellung des Artefakts, gegebenenfalls Schwachstellenrichtlinie, unveränderliche Artefaktidentität, Veröffentlichungs-Tag oder Workload-Revision und Zustand aus Kundensicht. Ein erfolgreicher Webhook des Anbieters oder ein erfolgreicher Klon der Quelle ist nur der Anfang dieser Kette.

Ablauf und Rotation von Tokens

Opfield erfasst, wann Tokens von GitLab-Connectoren und persönliche GitLab-Tokens von Benutzern ablaufen, und prüft sie täglich.

• Alarme: Opfield alarmiert 30 und 7 Tage, bevor ein Connector-Token, ein persönliches GitLab-Token oder die Autorisierung einer über OAuth verbundenen Integration abläuft, sofern der Ablauf bekannt ist. GitLab meldet den Ablauf seiner Tokens; GitHub- und generische Git-Tokens sind abgedeckt, wenn sie über OAuth verbunden sind.
• Selbstrotation bei GitLab: 14 Tage vor dem Ablauf rotiert Opfield Tokens von GitLab-Connectoren und persönliche GitLab-Tokens, die den Scope api oder self_rotate haben. Das neue Token behält die vorherige Laufzeit, zwischen 30 Tagen und einem Jahr, und ersetzt das gespeicherte Secret; die Rotation wird auditiert. Projekt- und Gruppen-Access-Tokens können sich über diesen Weg nicht selbst rotieren und erhalten nur Alarme.
• Abgelaufene Tokens: Opfield verwendet ein Token nicht mehr, sobald es abgelaufen ist. Ein abgelaufenes persönliches GitLab-Token schlägt mit GIT_CREDENTIAL_EXPIRED (HTTP 428) fehl, sodass der Benutzer ein neues autorisieren muss; ein abgelaufenes Token eines GitLab-Connectors schlägt mit CONNECTOR_TOKEN_EXPIRED (HTTP 409) fehl. Das Ersetzen eines abgelaufenen Connector-Tokens erfordert das alte nicht.

Synchronisationen, Docker-Quellen und Pages-Builds, die von einem abgelaufenen Token abhängen, funktionieren nicht mehr, bis es ersetzt wird; behandeln Sie daher den 30-Tage-Alarm als Rotationsfrist für Tokens, die Opfield nicht selbst rotieren kann.

Rotation, Migration und Entfernung

Um Zugangsdaten zu rotieren, fügen Sie den Ersatz beim Anbieter und in Opfield hinzu, prüfen Sie die Erkennung und einen echten Build und widerrufen Sie dann den vorherigen Wert. Um Anbieter oder Repositories zu migrieren, frieren Sie automatische Deployments ein, halten Sie den letzten freigegebenen Commit und Artefakt-Digest fest, konfigurieren Sie die Ersatzquelle, vergleichen Sie den aufgelösten Tree, führen Sie einen Canary-Build aus und verschieben Sie den Produktionszeiger erst nach der Prüfung ausdrücklich.

Listen Sie vor dem Löschen eines Connectors jede Abhängigkeit von Docker, Compose, Pages, Registries, Webhooks und Automatisierung auf. Deaktivieren Sie zuerst die Auslöser. Bestehende unveränderliche Artefakte können weiterlaufen, aber künftige Builds, Aktualisierungen oder quellbasierte Wiederherstellung können fehlschlagen, nachdem der Connector verschwunden ist. Behalten Sie das letzte freigegebene Artefakt und die Rollback-Anleitung, bis der neue Quellweg einen Betriebszyklus überstanden hat.

Sicherheitsprüfung

Prüfen Sie Audit-Logs des Anbieters, Berechtigungen installierter Anwendungen, Deploy-Schlüssel, SSH-Host-Schlüssel, Webhook-Secrets, erlaubte Organisationen bzw. Repositories und inaktive Bindings. Lesender Repository-Zugriff kann proprietäre Quellen und Konfiguration offenlegen; Schreib- oder Workflow-Berechtigungen können die Software-Lieferkette beeinflussen. Vergeben Sie sie nur, wenn der gewählte Opfield-Ablauf sie erfordert.

Repository-Prüfung, geschützte Branches, Abhängigkeitsrichtlinie und Freigabe von Artefakten bleiben bei Ihrem Git-Anbieter und in Ihrem Prüfprozess. Opfield baut und stellt darauf aufbauend bereit, mit Scopes und Audit, und folgt Ihrer Quellrichtlinie, statt sie zu umgehen.