Es gibt viele Szenarien, in denen Sie Codesphere mit einem Drittsystem verbinden oder bestimmte Arbeitsabläufe im Zusammenhang mit Codesphere automatisieren möchten, um die Anforderungen Ihres Teams zu erfüllen.

Die tatsächlich verfügbaren Endpunkte in der aktuellsten Version finden Sie unter https://codesphere.com/api/swagger-ui oder, wenn Ihr Unternehmen eigene Codesphere-Installationen betreibt, unter https://[Your_Base_URL]/api/swagger-ui.

Die Swagger-Benutzeroberfläche ist immer auf dem neuesten Stand und ermöglicht das Testen jedes Endpunkts direkt von der Benutzeroberfläche aus. Der Rest dieses Dokuments führt durch den Authentifizierungsprozess und zeigt einige Beispiele für die Verwendung der API.

Authentifizierung

Viele Endpunkte erfordern eine Authentifizierung über einen API-Schlüssel. Sie können diese innerhalb von Codesphere über das Konto-Avatar-Menü in der oberen rechten Ecke erstellen. Unter API-Schlüssel können Sie so viele Token erstellen, wie Sie benötigen. Achten Sie darauf, das Token zu kopieren, nachdem es erstellt wurde - Sie können es später nicht mehr abrufen.

Dieses Token dient derzeit als persönliches Zugriffstoken, um die API zu ermächtigen, in Ihrem Namen zu handeln. Das bedeutet, dass es die gleiche Zugriffsebene wie Ihr Konto hat - es kann alle Ressourcen der Teams, denen Sie angehören, sehen und mit ihnen interagieren. In Zukunft werden wir fein abgestufte Token mit einer detaillierteren Kontrolle hinzufügen.

Sobald Sie Ihren API-Schlüssel bereit haben, können Sie mit den Endpunkten interagieren. Die Swagger-Benutzeroberfläche bietet auch die Möglichkeit, den API-Schlüssel als bearerAuth einzugeben - nach der Eingabe können Sie mit dem Testen der Endpunkte beginnen.

Beliebte API-Testtools wie Postman ermöglichen auch das Hinzufügen dieser Token für umfangreichere Tests.

Release Fluss

Während einzelne Endpunkte für sich genommen wertvoll sein können, ergibt sich der wahre Wert aus der Kombination mehrerer API-Aufrufe zu einem vollständigen User-Flow.

Das erste Beispiel, das wir uns ansehen wollen, ist die Erstellung eines Releases über ein Skript (d.h. Run on merge in einer GitHub-Action).

Einfacher Fall

1. Führen Sie einen Git-Pull in Ihrem Workspace über die API /workspaces/{workspaceId}/git/pull/{remote} durch, zum Beispiel: /workspaces/64286/git/pull/origin
2. (Optional) Bauen Sie Ihre Anwendung mit /workspaces/{workspaceId}/pipeline/prepare/start neu auf
3. Warten Sie auf das Ende der Prepare-Phase, d. h. rufen Sie /workspaces/{workspaceId}/pipeline/prepare ab, bis der Wert 200 zurückgegeben wird.
4. Stoppen Sie Ihre Anwendung, indem Sie zunächst die Run-Phase mit /workspaces/{workspaceId}/pipeline/run/stop anhalten
5. Starten Sie die Anwendung neu mit /workspaces/{workspaceId}/pipeline/run/start

Automatisierung von Zero Downtime Releases

Der einfache Fall eignet sich hervorragend für statische Websites und Anwendungen, die sofort neu gestartet werden können (z. B. wir verwenden dies für unsere Website). Wenn Sie jedoch ein Zero Downtime Release automatisieren möchten, ist dies ebenfalls möglich. Führen Sie bei dem von Ihnen gewünschten Auslöser (d. h. einer Zusammenführung oder manuell) den folgenden Ablauf aus:

1. Erstellen Sie einen neuen Workspace mit dem gewünschten Git-Commit über /workspaces. Sie benötigen die Team-ID, die Plan-ID, die Git-Url (+ Boolesche Angabe, ob privat oder nicht), den Zweig und die Anzahl der Replicas.
2. Installieren und erstellen Sie alle erforderlichen Abhängigkeiten durch Ausführen der Prepare-Stufe /workspaces/{workspaceId}/pipeline/prepare/start dd
3. Warten Sie auf das Ende der Prepare-Phase, d. h. rufen Sie /workspaces/{workspaceId}/pipeline/prepare ab, bis der Wert 200 zurückgegeben wird.
4. (Optional) Wenn Ihre ci.yml in der Testphase Unit-Tests o.ä. definiert, führen Sie diese aus und überprüfen Sie das Ergebnis mit /workspaces/{workspaceId}/pipeline/test/start
5. (Optional) Warten Sie auf das Ende der Testphase, d. h. rufen Sie /workspaces/{workspaceId}/pipeline/test ab, bis 200 zurückgegeben wird - brechen Sie den Vorgang ab, wenn ein Test fehlschlägt.
6. Starten Sie die Anwendung mit /workspaces/{workspaceId}/pipeline/run/start
7. (Optional) Führen Sie Integrationstest-Pipelines gegen die neu erstellte Workspace-URL aus oder überprüfen Sie manuell, ob die neue Anwendung und die Git-Übertragung wie geplant funktionieren.
8. Wenn Sie erfolgreich sind, aktualisieren Sie den Workspace, der mit Ihrer produktiven Domäne verbunden ist, mit /domains/team/{teamId}/domain/{domainName}/workspace-connections - das aktuelle Schema, das Sie dafür benötigen, finden Sie in Swagger