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 gemergt werden.

Architekturübersicht

Entsprechende barrierefreie Textbeschreibung

Voraussetzungen

Stelle vor der Einrichtung der Automatisierung sicher, dass Folgendes bereitsteht:

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

Empfohlen: Verwendung eines Service-Accounts

Für Produktivumgebungen empfehlen wir dringend die Verwendung eines Service-Accounts (eines dedizierten Maschinenbenutzers) anstelle eines persönlichen Entwicklerkontos. Dies verhindert, dass die Automatisierung ausfällt, 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 bei 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 dieser über die notwendigen Berechtigungen verfügt, um auf dein GitHub-Repository zuzugreifen.
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: E-Mail-/Passwort-Authentifizierung

Die Authentifizierung mit email und password ist veraltet. Verwende stattdessen apiToken. Die alten Eingaben funktionieren weiterhin, geben jedoch bei jedem Workflow-Lauf eine Warnung zur 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 dein 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, das unter Account Settings > API Keys generiert wurde.
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

Du musst eine GitHub-Actions-Workflow-Datei erstellen, die auf Pull-Request-Ereignisse wartet.

6. Erstelle das Verzeichnis .github/workflows/ im Wurzelverzeichnis deines 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:
          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

Teamname

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. Generiere 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	Bei true verwendet der Workspace den Modus „Off when unused“, um Kosten zu sparen (wacht bei Zugriff wieder 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 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 auf die Entwicklungsdomain des Workspace.	dev-domain
sharedVaultName	Nein	Name eines Team Shared Vault, der mit dem Workspace verbunden werden soll. Wenn gesetzt, verwendet das Preview-Deployment die Secrets des Vaults erneut, anstatt einen eigenen isolierten Satz zu pflegen, sodass Secrets nur einmal 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.	-
ciProfile	Nein	Name des CI-Profils, das für das Deployment verwendet werden soll.	Die ci.yml des Repositorys
restricted	Nein	Bei true ist die Entwicklungsdomain des Workspace nur für Teammitglieder erreichbar, anstatt öffentlich zu sein.	false
baseImage	Nein	Überschreibt das Basis-Image, aus dem der Workspace erstellt wird.	Das Standard-Image des Plans
vpnConfig	Nein	Name einer Team-VPN-Konfiguration, mit der das Preview-Deployment verbunden werden soll.	-
cloneDepth	Nein	Tiefe des Shallow-Clone beim Auschecken des Repositorys.	Vollständiger Verlauf
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. Nutze dies nur für selbst gehostete Instanzen mit selbstsignierten Zertifikaten.	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 in deinem Repository.
11. Überprüfe den Statusbereich des PR.

Erfolg

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

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.