Version: Weekly Build

GitHub Preview Deployments

info

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

Architektonischer Überblick

Architekturdiagramm für GitHub Preview Deployments — Zugehörige barrierefreie Textbeschreibung

Voraussetzungen

Bevor die Automatisierung eingerichtet wird, stelle sicher, dass Folgendes vorhanden ist:

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

Empfohlen: Verwendung eines Service Accounts

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

Service Account erstellen: Registriere dich für ein neues Codesphere-Konto mit einem dedizierten E-Mail-Alias, z. B. [email protected].
Zum Team einladen: Melde dich bei deinem Haupt-Codesphere-Konto an und lade diesen neuen Service Account zu deinem Ziel-Team ein.
Git verbinden: Melde dich als Service Account an und stelle sicher, dass er die notwendigen Berechtigungen hat, um auf dein GitHub-Repository zuzugreifen.
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 aber eine Deprecation-Warnung in deinem Workflow-Lauf aus.

GitHub Secrets konfigurieren

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

Öffne dein Repository auf GitHub.
Navigiere zu Settings > Secrets and Variables > Actions.
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) Deine Codesphere-Login-E-Mail-Adresse. Verwende stattdessen `CODESPHERE_API_TOKEN`.
`CODESPHERE_PASSWORD`	(Veraltet) Dein Codesphere-Kontopasswort. Verwende stattdessen `CODESPHERE_API_TOKEN`.

Workflow-Datei hinzufügen

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

Erstelle das Verzeichnis .github/workflows/ im Root deines Repositories.
Erstelle eine Datei mit dem Namen main.yml in diesem Verzeichnis.
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 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
          ciProfile: 'my-ci-profile'  # Optional: CI profile to use instead of the default
          restricted: 'false'    # Optional: 'true' restricts the dev domain to team members only
          baseImage: 'my-base-image'  # Optional: overrides the workspace's base image
          vpnConfig: 'my-vpn-config'  # Optional: attach the workspace to an existing team 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

Team-Name

Achte darauf, 'My Team' durch den exakten Namen deines Teams in Codesphere zu ersetzen (Groß-/Kleinschreibung beachten). Diesen findest du 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
`apiToken`	Empfohlen	Dein Codesphere-API-Token. Wenn angegeben, werden `email` und `password` ignoriert. Erstelle eines unter Account Settings > API Keys.	-
`email`	Veraltet	Die E-Mail-Adresse deines Codesphere-Kontos. Verwende stattdessen `apiToken`.	-
`password`	Veraltet	Das Passwort deines Codesphere-Kontos. Verwende stattdessen `apiToken`.	-
`team`	Ja	Der exakte Name deines Teams in Codesphere.	-
`plan`	Nein	Der Compute-Plan für den Workspace.	`Boost` Optionen: `Micro`, `Boost`, `Pro`
`onDemand`	Nein	Wenn `true`, nutzt der Workspace den Modus „Off when unused“, um Kosten zu sparen (wacht bei Zugriff auf).	`false`
`apiUrl`	Nein	Die Basis-URL für deine 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 Entwicklungsdomain des Workspace.	`dev-domain`
`sharedVaultName`	Nein	Name eines Team Shared Vaults, der mit dem Workspace verbunden werden soll. Wenn gesetzt, nutzt 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 geteilt werden. Der Shared Vault muss im Team bereits 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	Wenn `true`, ist die Dev-Domain des Workspace nur für Teammitglieder erreichbar, anstatt öffentlich zu sein.	`false`
`baseImage`	Nein	Überschreibt das Base Image, aus dem der Workspace erstellt wird.	Das Standardimage des Plans
`vpnConfig`	Nein	Name einer Team-VPN-Konfiguration, mit der das Preview-Deployment verbunden werden soll.	-
`cloneDepth`	Nein	Shallow-Clone-Tiefe, die beim Checkout des Repositories verwendet wird.	Vollständiger Verlauf
`skipLfs`	Nein	Wenn `true`, wird das Herunterladen (Smudging) von Git-LFS-Dateien beim Klonen übersprungen.	`false`
`recurseSubmodules`	Nein	Wenn `false`, werden Submodule nicht initialisiert und geklont.	`true`
`tlsAllowUnauthorized`	Nein	Wenn `true`, wird die TLS-Zertifikatsprüfung bei der Kommunikation mit der Codesphere-API deaktiviert. Verwende dies nur für selbst gehostete Instanzen mit selbstsignierten Zertifikaten.	`false`

Format von Umgebungsvariablen

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

Deployment & Verifizierung

Committe und pushe die Datei main.yml.
Öffne einen neuen Pull Request in deinem Repository.
Überprüfe den PR-Statusbereich.

Erfolg

Du siehst einen "Deploy"-Check mit einem direkten Link zu deiner Preview-Umgebung.

Statusansicht eines GitHub Pull Requests mit dem Preview-Deployment-Check und Link.

Bereinigung

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

info

Architektonischer Überblick

Voraussetzungen​

Empfohlen: Verwendung eines Service Accounts​

Veraltet: Authentifizierung mit E-Mail/Passwort

GitHub Secrets konfigurieren​

Workflow-Datei hinzufügen​