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.
- Service-Konto erstellen: Registriere ein neues Codesphere-Konto mit einem dedizierten E-Mail-Alias, z. B.
[email protected]. - Zum Team einladen: Melde dich mit deinem Haupt-Codesphere-Konto an und lade dieses neue Service-Konto zu deinem Ziel-Team ein.
- 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.
- 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:
- Bei Codesphere abmelden.
- Auf dem Login-Bildschirm auf Passwort vergessen klicken.
- 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.
- Ö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_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.
- Erstelle das Verzeichnis
.github/workflows/im Root deines Repositorys. - Erstelle eine Datei mit dem Namen
main.ymlin 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:
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
- Committe und pushe die Datei
main.yml. - Öffne einen neuen Pull Request in deinem Repository.
- 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.