GitHub Preview Deployments
info
Dieser Leitfaden erklärt, wie automatisch ein Preview Codesphere Workspace für jeden Pull Request (PR) erstellt wird, der in eurem GitHub-Repository geöffnet wird. Dadurch kann euer Team Änderungen in einer Live-Umgebung überprüfen, bevor sie gemergt 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
Wir arbeiten derzeit an einem dedizierten API-Token-System. Sobald dieses verfügbar ist, kann die Authentifizierung über Tokens statt über Kontopasswörter erfolgen.
Empfehlung: 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 unterbrochen wird, falls ein Teammitglied das Unternehmen verlässt.
- Service Account erstellen: Registriert ein neues Codesphere-Konto mit einem dedizierten E-Mail-Alias, z. B.
[email protected]. - Zum Team einladen: Meldet euch mit eurem Haupt-Codesphere-Konto an und ladet diesen neuen Service Account in euer Ziel-Team ein.
- Git verbinden: Meldet euch als Service Account an und stellt sicher, dass er die nötigen Berechtigungen hat, um auf euer GitHub-Repository zuzugreifen.
- Passwort festlegen: Da für die Automatisierung kein OAuth verwendet werden kann, muss für diesen Service Account ein Passwort gesetzt sein (nutzt bei Bedarf den „Passwort vergessen“-Ablauf, falls die Registrierung über GitHub/Google erfolgt ist).
Wichtig: Passwort erforderlich
GitHub Actions benötigt einen Standard-Login mit E-Mail/Passwort. Wenn der Service Account über OAuth erstellt wurde, muss ein Passwort festgelegt werden:
- Meldet euch von Codesphere ab.
- Klickt auf dem Login-Bildschirm auf Passwort vergessen.
- Folgt den Anweisungen in der E-Mail, 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.
- Öffnet euer Repository auf GitHub.
- Navigiert zu Settings > Secrets and Variables > Actions.
- Klickt auf New repository secret und fügt die folgenden zwei Secrets hinzu:
| Secret-Name | Wert |
|---|---|
CODESPHERE_EMAIL | Eure Codesphere-Login-E-Mail-Adresse. |
CODESPHERE_PASSWORD | Das Passwort, das im Schritt „Voraussetzungen“ festgelegt wurde. |
Workflow-Datei hinzufügen
Ihr müsst eine GitHub Actions Workflow-Datei erstellen, die auf Pull-Request-Ereignisse reagiert.
- Erstellt das Verzeichnis
.github/workflows/im Root eures Repositorys. - Erstellt eine Datei mit dem Namen
main.ymlin diesem Verzeichnis. - Fügt 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@v4
- 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
Team-Name
Achtet darauf, 'My Team' durch den exakten Namen eures Teams in Codesphere zu ersetzen (Groß-/Kleinschreibung beachten). Diesen findet ihr oben links in 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 eures Codesphere-Kontos. | - |
password | Ja | Das Passwort eures Codesphere-Kontos. | - |
team | Ja | Der exakte Name eures Teams in Codesphere. | - |
plan | Nein | Der Compute-Plan für den Workspace. | Boost Optionen: Micro, Boost, Pro |
onDemand | Nein | Bei true nutzt der Workspace den Modus „Off when unused“, um Kosten zu sparen (wird bei Zugriff automatisch aktiviert). | false |
apiUrl | Nein | Die Basis-URL für eure Codesphere-API. | https://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 zur Entwicklungsdomain des Workspace. | dev-domain |
Format der Umgebungsvariablen
Verwendet eine dotenv-ähnliche Definition der Umgebungsvariablen. Details siehe https://www.npmjs.com/package/dotenv.
Bereitstellen & Überprüfen
- Committet und pusht die Datei
main.yml. - Öffnet einen neuen Pull Request in eurem Repository.
- Prüft den Statusbereich des PR.
Erfolg
Ihr seht einen „Deploy“-Check mit einem direkten Link zu eurer Preview-Umgebung.
Aufräumen
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.