GitHub Preview Deployments

info

Diese Anleitung erklärt, wie automatisch ein Preview Codesphere Workspace für jeden Pull Request (PR) erstellt wird, der in deinem GitHub-Repository geöffnet wird. Dadurch kann dein 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

Zukünftige API-Unterstützung

Derzeit wird an einem dedizierten API-Token-System gearbeitet. Sobald dieses veröffentlicht ist, kann die Authentifizierung über Token statt über Kontopasswörter erfolgen.

Empfohlen: Verwendung eines Service Accounts

Für produktive Umgebungen wird dringend empfohlen, einen Service Account (einen dedizierten Maschinen-Benutzer) anstelle eines persönlichen Entwicklerkontos zu verwenden. Dadurch wird verhindert, dass die Automatisierung unterbrochen wird, wenn ein Teammitglied das Unternehmen verlässt.

1. Service Account erstellen: Registriere ein neues Codesphere-Konto mit einem dedizierten E-Mail-Alias, z. B. [email protected].
2. Zum Team einladen: Melde dich in deinem Haupt-Codesphere-Konto an und lade diesen neuen Service Account zu deinem Ziel-Team ein.
3. Git verbinden: Melde dich als Service Account an und stelle sicher, dass er über die notwendigen Berechtigungen verfügt, um auf dein GitHub-Repository zuzugreifen.
4. Passwort festlegen: Da OAuth für die Automatisierung nicht verwendet werden kann, muss für diesen Service Account ein Passwort festgelegt sein (nutze den "Passwort vergessen"-Ablauf, falls die Registrierung über GitHub/Google erfolgte).

Wichtig: Passwortanforderung

GitHub Actions benötigt einen Standard-Login mit E-Mail und Passwort. Wurde der Service Account über OAuth erstellt, muss ein Passwort festgelegt werden:

1. Von Codesphere abmelden.
2. Auf dem Login-Bildschirm auf Passwort vergessen klicken.
3. Den Anweisungen in der E-Mail folgen, um ein Passwort für den Service Account festzulegen.

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_EMAIL	Die E-Mail-Adresse für den Codesphere-Login.
CODESPHERE_PASSWORD	Das Passwort, das im Schritt "Voraussetzungen" festgelegt wurde.

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 Root-Verzeichnis des Repositorys.
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:
          email: ${{ secrets.CODESPHERE_EMAIL }}
          password: ${{ secrets.CODESPHERE_PASSWORD }}
          team: 'My Team'         # <--- REPLACE with your Team 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 team shared vault's secrets across preview deployments
          env: |                  # Optional: Add environment variables below
            MY_ENV=test
            DEBUG=true

Teamname

Stelle sicher, dass 'My Team' durch den exakten Namen deines Teams in Codesphere ersetzt wird (Groß-/Kleinschreibung beachten). Dieser findet sich in der oberen linken Ecke der Codesphere-Benutzeroberfläche.

Konfigurationsreferenz

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

Option	Erforderlich	Beschreibung	Standard / Werte
email	Ja	Die E-Mail-Adresse des Codesphere-Kontos.	-
password	Ja	Das Passwort des Codesphere-Kontos.	-
team	Ja	Der exakte Name des Teams in Codesphere.	-
plan	Nein	Der Compute-Plan für den Workspace.	Boost Optionen: Micro, Boost, Pro
onDemand	Nein	Bei true verwendet 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 injiziert 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 auf die Development-Domain des Workspace.	dev-domain
sharedVaultName	Nein	Name eines Team Shared Vaults, der dem Workspace zugeordnet wird. Ist dies gesetzt, verwendet das Preview-Deployment die Secrets des Vaults, anstatt einen eigenen isolierten Satz zu pflegen, sodass Secrets einmalig gepflegt und über alle Preview-Workspaces hinweg geteilt werden können. Der Shared Vault muss bereits im Team konfiguriert sein. Siehe Secret Management → Shared Vaults.	-

Format der Umgebungsvariablen

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

Deployen & Überprüfen

9. Committe und pushe die Datei main.yml.
10. Öffne einen neuen Pull Request in deinem Repository.
11. Prüfe den PR-Statusbereich.

Erfolg

Ein "Deploy"-Check mit einem direkten Link zur Preview-Umgebung wird angezeigt.

Bereinigung

Wird der Pull Request geschlossen oder zusammengeführt, fährt dieser Workflow den Preview-Workspace automatisch herunter und löscht ihn, damit keine Kosten für ungenutzte Ressourcen entstehen.