Aus einem privaten Repo ausrollen

Private Repos rollen Sie genauso aus wie öffentliche, sobald nyxory sie lesen kann. Wie nyxory sie liest, hängt davon ab, wo das Repo liegt:

Wo das Repo liegt	Wie nyxory es liest
github.com	Die nyxory GitHub App: einmal im Browser installieren, danach kurzlebige Tokens. Kein Deploy-Key, kein PAT.
Jeder andere Git-Host (GitLab, Bitbucket, selbst betrieben)	Eine HTTPS-Git-Verbindung: Benutzername und Zugriffstoken eines Service-Accounts, einmal pro Workspace gespeichert.
Gerrit, mit Ihrer Instanz verbunden	Ein Lesekonto pro Projekt: überhaupt kein Token, der Repo-Inhaber berechtigt in Gerrit jedes Projekt einzeln.

Alle drei Wege funktionieren in jedem Tarif.

Voraussetzungen

• Ein mit nyxory verbundener Agent (siehe Agent verbinden)
• Für GitHub: Admin-Zugriff auf das Repo oder die Organisation, die Sie verbinden wollen
• Für andere Hosts: Sie sind Inhaber des Workspace und haben einen Service-Account mit Lesezugriff auf das Repo

GitHub

1. Einfach den Auftrag geben.

   Roll https://github.com/me/private-widget auf nyxory aus

   Ihr Agent ruft nyx_brain auf und versucht dann, das Repo zu klonen. Bei einem öffentlichen Repo ist die Sache damit erledigt. Bei einem privaten scheitert der Klon mit einem Authentifizierungsfehler.

2. Der Agent gibt Ihnen einen Installationslink.

   Nach dem Fehlschlag ruft der Agent nyx_github_install_url auf und gibt Ihnen eine signierte Installations-URL. Der Link läuft nach 10 Minuten ab. Ist er abgelaufen, erzeugt der Agent einfach einen neuen. Der Aufruf ist idempotent.

3. App im Browser installieren.

   Öffnen Sie den Link, wählen Sie die Repositorys, die nyxory erreichen soll (oder die ganze Organisation), und klicken Sie auf Install. Es ist eine gewöhnliche GitHub App: auf Repos beschränkt, in Ihren GitHub-Einstellungen sichtbar und dort jederzeit widerrufbar. Sie können die Installation auch in der Console starten, über GitHub im Workspace-Menü.

4. Ihrem Agenten Bescheid geben.

   Er versucht den Klon erneut über nyx_clone_repo. Das Repo landet im Arbeitsverzeichnis Ihres Projekts, und der Deploy läuft genau wie bei einem öffentlichen Repo weiter. Decken mehrere Installationen denselben GitHub-Owner ab, klärt der Agent das mit nyx_github_list (erst die Installationen, dann kind: repos).

Builds klonen das Repo mit einem kurzlebigen Installationstoken (etwa eine Stunde gültig), das Ihr Dockerfile nie zu sehen bekommt. Details unter Builds und die Ausführungsumgebung.

Teilen im Workspace. Ein Repo, das Sie in einem gemeinsamen Workspace ausrollen, kommt automatisch zu den geteilten Repositorys des Workspace. Mitglieder können es dann mit Ihrem GitHub-Zugang in ihren Projekten ausrollen. Der Inhaber verwaltet diese Liste unter Team > Shared repositories und kann dort ein Repo entfernen.

Andere Git-Hosts per HTTPS anbinden

Bei GitLab, Bitbucket oder einem selbst betriebenen Git-Server verbindet der Workspace-Inhaber das Repository einmal in der Console:

1. Öffnen Sie GitHub im Workspace-Menü. Wenn HTTPS-Verbindungen verfügbar sind, heißt die Seite Git connections.
2. Klicken Sie unter Other Git repositories auf Connect repository und tragen Sie einen Namen, die Repository URL (HTTPS), den Service account username und dessen Access token ein. Ein Ablaufdatum für das Token ist optional. Die Console zeigt es neben der Verbindung an.
3. Legen Sie fest, wer die Verbindung nutzen darf. Mit Share with workspace kann jedes Mitglied das Repo in seinen Projekten ausrollen, sonst bleibt es bei Owner only.
4. Check main prüft, ob die Zugangsdaten das Repo lesen können, bevor jemand daraus baut.

Danach geben Sie Aufträge wie gewohnt. Ihr Agent klont mit nyx_clone_repo und übergibt dabei die connection_id der Verbindung. Builds nutzen die gespeicherten Zugangsdaten für ihren Klon-Schritt. Setzen Sie ein Ablaufdatum und rotieren Sie das Token auf Ihrer Seite. nyxory verkürzt seine Laufzeit nicht.

• Die Anmeldung nutzt Benutzername und Token zusammen, ein Token allein reicht nicht. Der Service-Account braucht nur Lesezugriff.
• Das gespeicherte Token wird nie wieder angezeigt. Edit credentials ersetzt es, Disable connection stoppt neue Builds über diese Verbindung, laufende Apps bleiben online.
• SSH-Deploy-Keys für andere Hosts werden nicht unterstützt. Verwenden Sie HTTPS mit einem Token.
• Auto-Deploy funktioniert auch für diese Repos. nyxory prüft den überwachten Branch etwa einmal pro Minute und baut jeden neuen Commit. Siehe Bei jedem Push ausrollen.

Hinweis: HTTPS-Git-Verbindungen sind für jeden Workspace auf der gemeinsamen nyxory-Plattform eingeschaltet. Auf einer dedizierten Instanz werden sie pro Instanz eingeschaltet.

Gerrit mit einem Lesekonto pro Projekt anbinden

Ist Ihre Instanz mit einem Gerrit-Server verbunden, nennt die Seite Git connections ihn, und Repos dort brauchen kein Token. Stattdessen bekommt jedes Projekt, das ein Gerrit-Repository nutzt, ein eigenes Gerrit-Konto mit reinem Lesezugriff. Es meldet sich per SSH mit einem Schlüssel an, den die Console erzeugt. Das Konto kann nichts lesen, bis der Repo-Inhaber ihm die Berechtigung erteilt.

1. Repository verbinden. Der Workspace-Inhaber nutzt Connect repository wie oben. Bei einer Gerrit-URL fragt das Formular nur nach Namen und URL, ohne Benutzernamen und ohne Token.
2. Wie gewohnt ausrollen. Beim ersten Deploy wird der Klon abgelehnt. Der Agent meldet das Konto des Projekts und einen Link zu den Zugriffseinstellungen des Repositorys in Gerrit.
3. Berechtigung erteilen. Der Repo-Inhaber öffnet den Link und erteilt unter Access der Gruppe mit dem Namen des Kontos die Berechtigung Read auf refs/*.
4. Erneut klonen. Sagen Sie Ihrem Agenten, dass die Berechtigung erteilt ist. Er versucht nyx_clone_repo erneut, und der Deploy läuft weiter.

Ist Auto-Deploy für die App eingerichtet, zeigt ihr Bereich Auto-deploy denselben Stand: zuerst Waiting for approval mit dem Konto und einem Link Open access in Gerrit, danach Reads over SSH as mit dem Konto des Projekts. Eine Berechtigung, die erteilt wird, während der Bereich wartet, wird innerhalb einer Minute erkannt, ohne dass Sie den Agenten fragen müssen.

Weil jedes Projekt ein eigenes Konto hat, öffnet die Berechtigung für ein Projekt das Repository nie für ein anderes Projekt, weder im selben Workspace noch anderswo. Siehe Projekte und Konten.

Zugriff verwalten

Welche GitHub-Konten sind mit nyxory verbunden?

Ihr Agent listet sie über nyx_github_list auf. Über den Widerruf des Zugriffs entscheidet ein Mensch, nicht Ihr Agent:

• In der Console: GitHub im Workspace-Menü listet die über nyxory verbundenen Installationen auf, mit einer Aktion zum Trennen pro Installation.
• In GitHub: Settings > Applications > Installed GitHub Apps > nyxory > Uninstall. Die Wirkung ist dieselbe.

Danach lassen sich für diese Installation keine neuen Tokens mehr erzeugen. Bereits ausgegebene kurzlebige Tokens laufen innerhalb einer Stunde ab.

Bei HTTPS-Verbindungen widerrufen Sie mit Disable connection auf der Seite Git connections. Bei Gerrit entzieht der Repo-Inhaber der Gruppe in Gerrit die Berechtigung Read.

Fehlerbehebung

Achtung:

1. Der Installationslink liefert 404 oder einen Fehler. Er ist abgelaufen (Zeitfenster von 10 Minuten). Bitten Sie Ihren Agenten um einen neuen. nyx_github_install_url signiert bei jedem Aufruf neu.
2. Installiert, aber der Klon schlägt weiter fehl. Prüfen Sie, ob das Repo wirklich in der Installation enthalten ist. Lassen Sie Ihren Agenten dazu nyx_github_list mit kind: repos für die Installation ausführen. Der full_name des Repos muss dort erscheinen. Haben Sie bei der Installation „selected repositories“ gewählt, fügen Sie das fehlende Repo in den App-Einstellungen bei GitHub hinzu.
3. Mehrere Organisationen, falsches Konto. Der Installationslink bindet sich an das GitHub-Konto, mit dem Sie gerade angemeldet sind. Melden Sie sich mit dem richtigen Konto an (oder nutzen Sie die Organisationsauswahl auf dem Installationsbildschirm von GitHub) und öffnen Sie einen neuen Link.
4. Die Organisation verlangt eine Freigabe. In Organisationen, in denen Sie kein Admin sind, stellt GitHub die Installation als Anfrage ein. Der Klon gelingt, sobald ein Admin der Organisation die Anfrage freigibt. Diese Freigabe liegt bei GitHub. Erinnern Sie also den Admin, statt die Installation erneut auszuführen.
5. Die HTTPS-Verbindung zeigt „Access failed“ oder „Credentials expired“. Das Token wurde widerrufen, ist abgelaufen oder hat keinen Lesezugriff. Ersetzen Sie es über Edit credentials durch ein neues und führen Sie Check main erneut aus.
6. Der Gerrit-Klon wird weiter abgelehnt, oder der Bereich bleibt bei „Waiting for approval“. Die Berechtigung fehlt oder ging an die falsche Gruppe. Der Gruppenname ist genau der Kontoname aus der Fehlermeldung oder aus dem Bereich.
7. Kommen Sie immer noch nicht weiter? Lassen Sie sich von Ihrem Agenten die genaue Fehlermeldung beim Klonen und die Ausgabe von nyx_github_list geben. Genau diese beiden Angaben fragen wir im Support ab.

Nächste Schritte

• Next.js-App ausrollen: der vollständige Deploy Schritt für Schritt
• Bei jedem Push ausrollen: bei jedem Commit auf den überwachten Branch neu ausrollen
• Builds und die Ausführungsumgebung: woher das Build-Token kommt