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überblick
Entsprechende barrierefreie Textbeschreibung
Voraussetzungen
Bevor die Automation eingerichtet wird, sollten folgende Punkte vorbereitet sein:
- Codesphere-Account
- 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 Account-Passwörtern erfolgen.
Empfehlung: Verwendung eines Service-Accounts
Für Produktionsumgebungen empfehlen wir dringend die Verwendung eines Service-Accounts (ein dedizierter Machine User) statt eines persönlichen Entwickler-Accounts. So wird verhindert, dass die Automation unterbrochen wird, wenn ein Teammitglied das Unternehmen verlässt.
- Service-Account erstellen: Registriere einen neuen Codesphere-Account mit einer dedizierten E-Mail-Alias-Adresse, z. B.
[email protected]. - Zum Team einladen: Melde dich mit deinem Haupt-Codesphere-Account an und lade diesen neuen Service-Account in dein Ziel-Team ein.
- Git verbinden: Melde dich als Service-Account an und stelle sicher, dass er die nötigen Berechtigungen hat, um auf dein GitHub-Repository zuzugreifen.
- Passwort setzen: Da für die Automation kein OAuth verwendet werden kann, muss für diesen Service-Account ein Passwort gesetzt sein (nutze den "Passwort vergessen"-Ablauf, falls die Registrierung über GitHub/Google erfolgt ist).
Wichtig: Passwort-Anforderung
GitHub Actions benötigt einen Standard-Login mit E-Mail/Passwort. Wurde der Service-Account über OAuth erstellt, muss ein Passwort definiert werden:
- Melde dich von Codesphere ab.
- Klicke auf dem Login-Bildschirm auf Passwort vergessen.
- Folge den Anweisungen in der E-Mail, um ein Passwort für den Service-Account zu setzen.
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" definiert wurde. |
Workflow-Datei hinzufügen
Es muss eine GitHub Actions Workflow-Datei erstellt werden, die auf Pull-Request-Events 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@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://cloud.codesphere.com' # replace with your instance URL
env: | # Optional: Add environment variables below
MY_ENV=test
DEBUG=true
Team-Name
Achte darauf, 'My Team' durch den exakten Namen deines Teams in Codesphere zu ersetzen (Groß-/Kleinschreibung beachten). Diesen findest du oben links in der Codesphere-UI.
Konfigurationsreferenz
Die folgenden Eingaben werden von der codesphere-cloud/gh-action-deploy-Action unterstützt:
| Option | Erforderlich | Beschreibung | Standard / Werte |
|---|---|---|---|
email | Ja | Die E-Mail-Adresse deines Codesphere-Accounts. | - |
password | Ja | Das Passwort deines Codesphere-Accounts. | - |
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 "Aus, wenn ungenutzt", um Kosten zu sparen (wacht bei Zugriff 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 injiziert werden (Key=Value-Format). | - |
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 Development-Domain des Workspace. | dev-domain |
Format der Umgebungsvariablen
Verwende eine dotenv-ähnliche Definition der Umgebungsvariablen. Details siehe https://www.npmjs.com/package/dotenv.
Deployen & Überprüfen
- Committe und pushe die Datei
main.yml. - Öffne einen neuen Pull Request in deinem Repository.
- Prüfe den Statusbereich des PR.
Erfolg
Es wird ein "Deploy"-Check mit einem direkten Link zu deiner Preview-Umgebung angezeigt.
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 anfallen.