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 bereitstehen:

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

Zukünftige API-Unterstützung

Wir arbeiten derzeit an einem dedizierten API-Token-System. Sobald dieses veröffentlicht ist, kann die Authentifizierung über Tokens anstelle von Konto-Passwörtern erfolgen.

Empfohlen: Verwendung eines Service-Kontos

Für Produktionsumgebungen empfehlen wir dringend die Verwendung eines Service-Kontos (ein dedizierter Maschinenbenutzer) anstelle eines persönlichen Entwicklerkontos. Dadurch wird verhindert, dass die Automatisierung ausfällt, wenn ein Teammitglied das Unternehmen verlässt.

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

Wichtig: Passwort-Anforderung

GitHub Actions erfordert einen standardmäßigen E-Mail-/Passwort-Login. Wurde das Service-Konto über OAuth erstellt, muss ein Passwort festgelegt werden:

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

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_EMAIL	Deine Codesphere-Login-E-Mail-Adresse.
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 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:
          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://codesphere.com' # Optional: Change for specific regions/instances
          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
email	Ja	Die E-Mail-Adresse deines Codesphere-Kontos.	-
password	Ja	Das Passwort deines Codesphere-Kontos.	-
team	Ja	Der exakte Name deines Teams in Codesphere.	-
plan	Nein	Der Rechenplan für den Workspace.	Boost Optionen: Micro, Boost, Pro
onDemand	Nein	Bei true verwendet der Workspace den Modus "Aus, wenn nicht verwendet", um Kosten zu sparen (aktiviert sich bei Zugriff automatisch).	false
apiUrl	Nein	Die Basis-URL für deine Codesphere-API.	https://codesphere.com
env	Nein	Eine Liste von Umgebungsvariablen, die in den Workspace injiziert werden sollen (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

Format für Umgebungsvariablen

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

Deployment & Überprüfung

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

Erfolg

Es erscheint ein "Deploy"-Check mit einem direkten Link zu deiner Vorschau-Umgebung.

Bereinigung

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