GitHub Preview Deployments

info

Diese Anleitung erklärt, wie automatisch ein Preview Codesphere Workspace für jeden Pull Request (PR) erstellt wird, der im GitHub-Repository geöffnet wird. Dadurch kann das Team Änderungen in einer Live-Umgebung überprüfen, bevor sie zusammengeführt werden.

Architekturübersicht

Entsprechende barrierefreie Textbeschreibung

Voraussetzungen

Bevor die Automatisierung eingerichtet wird, sollte Folgendes vorbereitet sein:

• Codesphere-Konto
• Admin-Zugriff auf das GitHub-Repository, das verbunden werden soll

Empfohlen: Verwendung eines Service-Accounts

Für Produktionsumgebungen wird dringend empfohlen, einen Service-Account (einen dedizierten Maschinennutzer) anstelle eines persönlichen Entwicklerkontos zu verwenden. Dies verhindert, dass die Automatisierung ausfällt, wenn ein Teammitglied das Unternehmen verlässt.

1. Service-Account erstellen: Registriere ein neues Codesphere-Konto mit einer dedizierten E-Mail-Alias, z. B. [email protected].
2. Zu Resource Group einladen: Melde dich im Haupt-Codesphere-Konto an und lade diesen neuen Service-Account zur gewünschten Resource Group ein.
3. Git verbinden: Melde dich als Service-Account an und stelle sicher, dass dieser über die nötigen Berechtigungen für den Zugriff auf das GitHub-Repository verfügt.
4. API-Token generieren: Gehe in Codesphere zu Account Settings > API Keys und erstelle ein neues Token für diesen Service-Account. Speichere es als GitHub Secret (siehe unten).

Veraltet: Authentifizierung mit E-Mail/Passwort

Die Authentifizierung mit email und password ist veraltet. Verwende stattdessen apiToken. Die alten Eingaben funktionieren weiterhin, geben jedoch im Workflow-Lauf eine Warnung bezüglich der Veraltung aus.

GitHub Secrets konfigurieren

Damit GitHub Actions sicher mit Codesphere kommunizieren kann, müssen die Zugangsdaten als verschlüsselte Secrets gespeichert werden.

1. Öffne das Repository auf GitHub.
2. Navigiere zu Settings > Secrets and Variables > Actions.
3. Klicke auf New repository secret und füge die folgenden zwei Secrets hinzu:

Secret-Name	Wert
CODESPHERE_API_TOKEN	Ein Codesphere-API-Token, erstellt unter Account Settings > API Keys.
CODESPHERE_EMAIL	(Veraltet) Die Codesphere-Login-E-Mail-Adresse. Verwende stattdessen CODESPHERE_API_TOKEN.
CODESPHERE_PASSWORD	(Veraltet) Das Codesphere-Kontopasswort. Verwende stattdessen CODESPHERE_API_TOKEN.

Workflow-Datei hinzufügen

Es muss eine GitHub Actions Workflow-Datei erstellt werden, die auf Pull-Request-Ereignisse reagiert.

6. Erstelle das Verzeichnis .github/workflows/ im Wurzelverzeichnis des Repositories.
7. Erstelle eine Datei mit dem Namen main.yml in diesem Verzeichnis.
8. Füge die folgende Konfiguration ein:

name: Codesphere Preview Deployment

on:
  workflow_dispatch:
  pull_request:
    types: [closed, opened, reopened, synchronize]

permissions:
  contents: read
  pull-requests: read
  deployments: write

jobs:
  deploy:
    name: Deploy to Codesphere
    # Prevent multiple workspaces from being created for the same PR
    concurrency: codesphere-preview-${{ github.event.pull_request.number }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v6

      - name: Deploy Preview
        uses: codesphere-cloud/gh-action-deploy@main
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          apiToken: ${{ secrets.CODESPHERE_API_TOKEN }}
          team: 'My Resource Group'  # <--- REPLACE with your resource group name
          plan: 'Boost'           # Options: Micro, Boost, Pro
          onDemand: 'true'        # 'true' enables cost-saving standby mode
          deploymentLinkType: 'preview' # Options: preview, dev-domain
          apiUrl: 'https://cloud.codesphere.com' # replace with your instance URL
          sharedVaultName: 'my-shared-vault'  # Optional: reuse a resource group shared vault's secrets across preview deployments
          ciProfile: 'my-ci-profile'  # Optional: CI profile to use instead of the default
          restricted: 'false'    # Optional: 'true' restricts the dev domain to resource group members only
          baseImage: 'my-base-image'  # Optional: overrides the workspace's base image
          vpnConfig: 'my-vpn-config'  # Optional: attach the workspace to an existing resource group VPN config
          cloneDepth: '1'         # Optional: shallow-clone depth for the checkout
          skipLfs: 'false'        # Optional: 'true' skips downloading Git LFS files
          recurseSubmodules: 'true' # Optional: 'false' skips cloning submodules
          tlsAllowUnauthorized: 'false' # Optional: 'true' disables TLS certificate verification
          env: |                  # Optional: Add environment variables below
            MY_ENV=test
            DEBUG=true

Name der Resource Group

Achte darauf, 'My Resource Group' durch den exakten Namen der Resource Group in Codesphere zu ersetzen (Groß-/Kleinschreibung beachten). Diesen findest du oben links in der Codesphere-Benutzeroberfläche.

Konfigurationsreferenz

Die folgenden Eingaben werden von der Action codesphere-cloud/gh-action-deploy unterstützt:

Option	Erforderlich	Beschreibung	Standard / Werte
apiToken	Empfohlen	Das Codesphere-API-Token. Wenn angegeben, werden email und password ignoriert. Erstellbar unter Account Settings > API Keys.	-
email	Veraltet	Die E-Mail-Adresse des Codesphere-Kontos. Verwende stattdessen apiToken.	-
password	Veraltet	Das Passwort des Codesphere-Kontos. Verwende stattdessen apiToken.	-
team	Ja	Der exakte Name der Resource Group in Codesphere.	-
plan	Nein	Der Compute-Plan für den Workspace.	Boost Optionen: Micro, Boost, Pro
onDemand	Nein	Bei true nutzt der Workspace den Modus „Off when unused“, um Kosten zu sparen (wacht bei Zugriff automatisch auf).	false
apiUrl	Nein	Die Basis-URL für die Codesphere-API.	https://cloud.codesphere.com
env	Nein	Eine Liste von Umgebungsvariablen, die in den Workspace eingefügt werden (Format Key=Value).	-
deploymentLinkType	Nein	Steuert das Format des Deployment-Links, der im PR gepostet wird. preview öffnet eine interaktive Vorschau, in der Reviewer Frontend-Kommentare hinterlassen können. dev-domain verlinkt direkt zur Dev-Domain des Workspace.	dev-domain
sharedVaultName	Nein	Name eines Shared Vaults der Resource Group, der an den Workspace angehängt wird. Wenn gesetzt, verwendet das Preview-Deployment die Secrets des Vaults, anstatt einen eigenen, isolierten Satz zu pflegen – so können Secrets einmal gepflegt und über alle Preview-Workspaces hinweg geteilt werden. Der Shared Vault muss bereits in der Resource Group konfiguriert sein. Siehe Secret Management → Shared Vaults.	-
ciProfile	Nein	Name des CI-Profils, das für das Deployment verwendet werden soll.	Die ci.yml des Repositories
restricted	Nein	Bei true ist die Dev-Domain des Workspace nur für Mitglieder der Resource Group erreichbar, anstatt öffentlich zu sein.	false
baseImage	Nein	Überschreibt das Base Image, aus dem der Workspace erstellt wird.	Das Standard-Image des Plans
vpnConfig	Nein	Name einer VPN-Konfiguration der Resource Group, mit der das Preview-Deployment verbunden wird.	-
cloneDepth	Nein	Shallow-Clone-Tiefe beim Auschecken des Repositories.	Vollständige Historie
skipLfs	Nein	Bei true wird das Herunterladen (Smudging) von Git-LFS-Dateien beim Klonen übersprungen.	false
recurseSubmodules	Nein	Bei false werden Submodule nicht initialisiert und geklont.	true
tlsAllowUnauthorized	Nein	Bei true wird die TLS-Zertifikatsprüfung bei der Kommunikation mit der Codesphere-API deaktiviert. Nur für selbst gehostete Instanzen mit selbstsignierten Zertifikaten verwenden.	false

Format der Umgebungsvariablen

Verwende eine dotenv-ähnliche Definition der Umgebungsvariablen. Details siehe https://www.npmjs.com/package/dotenv.

Bereitstellen & Überprüfen

9. Committe und pushe die Datei main.yml.
10. Öffne einen neuen Pull Request im Repository.
11. Überprüfe den Statusbereich des PR.

Erfolg

Es erscheint ein „Deploy“-Check mit einem direkten Link zur Preview-Umgebung.

Bereinigung

Beim Schließen oder Zusammenführen des Pull Requests fährt dieser Workflow den Preview-Workspace automatisch herunter und löscht ihn, sodass keine Kosten für ungenutzte Ressourcen entstehen.