Zum Hauptinhalt springen
Version: Weekly Build

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

Diagramm der GitHub-Preview-Deployment-Architektur

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-NameWert
CODESPHERE_EMAILDie E-Mail-Adresse für den Codesphere-Login.
CODESPHERE_PASSWORDDas 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.

  1. Erstelle das Verzeichnis .github/workflows/ im Root-Verzeichnis des Repositorys.
  2. Erstelle eine Datei mit dem Namen main.yml in diesem Verzeichnis.
  3. 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:

OptionErforderlichBeschreibungStandard / Werte
emailJaDie E-Mail-Adresse des Codesphere-Kontos.-
passwordJaDas Passwort des Codesphere-Kontos.-
teamJaDer exakte Name des Teams in Codesphere.-
planNeinDer Compute-Plan für den Workspace.Boost
Optionen: Micro, Boost, Pro
onDemandNeinBei true verwendet der Workspace den Modus "Off when unused", um Kosten zu sparen (wacht bei Zugriff automatisch auf).false
apiUrlNeinDie Basis-URL für die Codesphere-API.https://cloud.codesphere.com
envNeinEine Liste von Umgebungsvariablen, die in den Workspace injiziert werden (Format Key=Value).-
deploymentLinkTypeNeinSteuert 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
sharedVaultNameNeinName 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​

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

Erfolg

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

Ansicht des GitHub-Pull-Request-Status mit dem Preview-Deployment-Check und Link.

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.