Gitlab Preview Deployment

Phase 1: Vorbereitung des Accounts

1. Lege ein Passwort für deinen Codesphere-Account fest (erforderlich für den API-Zugriff).
   • Hinweis: Falls du dich über Google/GitHub angemeldet hast, nutze den Link "Passwort vergessen", um ein eigenes Passwort festzulegen.
2. Verbinde deinen GitLab-Account mit Codesphere.
   • Aktion: Klicke auf "+ New Workspace" und wähle "Connect GitLab" zur Autorisierung.
3. Erstelle ein GitLab Project Access Token.
   • Scopes: Wähle api.
   • Rolle: Wähle Developer.
   • Kopieren: Speichere dieses Token sofort; du benötigst es für die Secrets.

Phase 2: Konfiguration der GitLab Secrets

4. Öffne dein Repository auf GitLab.
5. Navigiere zu Settings > CI/CD > Variables.
6. Füge die folgenden Variablen hinzu (deaktiviere "Protect variable", falls dein Branch nicht geschützt ist):
   • CODESPHERE_API_TOKEN: Dein Codesphere-API-Token, generiert unter Account Settings > API Keys (empfohlen).
   • CI_ACCESS_TOKEN: Das in Phase 1 erstellte Project Access Token.
   • CODESPHERE_EMAIL: (Veraltet) Deine Codesphere-Login-E-Mail-Adresse. Verwende stattdessen CODESPHERE_API_TOKEN.
   • CODESPHERE_PASSWORD: (Veraltet) Dein Codesphere-Login-Passwort. Verwende stattdessen CODESPHERE_API_TOKEN.

Phase 3: Konfiguration der Pipeline

7. Erstelle eine .gitlab-ci.yml-Datei im Root-Verzeichnis deines Repositories.
8. Füge die folgende Konfiguration ein:

workflow:
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

stages:
  - deploy

codesphere-deploy:
  image: ghcr.io/codesphere-cloud/codesphere-monorepo/integrations/gitlab-ci:latest
  stage: deploy
  script:
    - node /app/server.js
  variables:
    API_URL: https://cloud.codesphere.com/ # replace with your instance URL
    ACCESS_TOKEN: $CI_ACCESS_TOKEN
    API_TOKEN: $CODESPHERE_API_TOKEN
    RESOURCE_GROUP: 'My Resource Group'  # REPLACE with your exact resource group name
    PLAN: 'Boost'         # Options: Micro, Boost, Pro
    ON_DEMAND: 'true'     # 'true' enables cost-saving standby mode
    DEPLOYMENT_LINK_TYPE: 'preview'  # Optional: 'preview' or 'dev-domain'
    SHARED_VAULT_NAME: 'my-shared-vault'  # Optional: reuse a resource group shared vault's secrets across preview deployments
    CI_PROFILE: 'my-ci-profile'  # Optional: CI profile to use instead of the default
    CODESPHERE_RESTRICTED: 'false'  # Optional: 'true' restricts the dev domain to resource group members only
    CODESPHERE_BASE_IMAGE: 'my-base-image'  # Optional: overrides the workspace's base image
    VPN_CONFIG: 'my-vpn-config'  # Optional: attach the workspace to an existing resource group VPN config
    GIT_CLONE_DEPTH: '1'   # Optional: shallow-clone depth for the checkout
    GIT_SKIP_LFS: 'false'  # Optional: 'true' skips downloading Git LFS files
    GIT_RECURSE_SUBMODULES: 'true'  # Optional: 'false' skips cloning submodules
    TLS_ALLOW_UNAUTHORIZED: 'false'  # Optional: 'true' disables TLS certificate verification
    ENV: |                # Optional: Add environment variables below
      MY_ENV=test

Shared Vaults

SHARED_VAULT_NAME verknüpft einen bestehenden Shared Vault der Resource Group mit dem Preview Deployment, sodass dessen Secrets wiederverwendet werden, anstatt einen eigenen isolierten Satz zu pflegen. Der Shared Vault muss bereits in der Resource Group konfiguriert sein. Siehe Secret Management → Shared Vaults.

Verfügbare Variablen

Die folgenden Variablen können unter dem Schlüssel variables des Jobs codesphere-deploy gesetzt werden. (*) = erforderliche Variable.

Variable	Verwendung
API_URL (*)	Die Basis-URL deiner Codesphere-Instanz inklusive https://, z. B. https://cloud.codesphere.com.
ACCESS_TOKEN (*)	Das in Phase 1 erstellte GitLab Project Access Token.
API_TOKEN	Empfohlen. Dein Codesphere-API-Token, generiert unter Account Settings > API Keys. Wenn gesetzt, werden EMAIL und PASSWORD ignoriert.
EMAIL	(Veraltet) E-Mail-Adresse des Codesphere-Nutzers. Verwende stattdessen API_TOKEN.
PASSWORD	(Veraltet) Passwort des Codesphere-Nutzers. Verwende stattdessen API_TOKEN.
RESOURCE_GROUP (*)	Name der Codesphere Resource Group. Der alte Name TEAM funktioniert weiterhin als Alias.
PLAN	Workspace-Plan des zu erstellenden Workspace. Verfügbare Optionen: Micro, Boost, Pro. Standard: Boost.
ON_DEMAND	Legt fest, ob dieses Preview Deployment im Always-on- oder Off-when-unused-Deployment-Modus bereitgestellt werden soll. Verfügbare Optionen: true, false.
ENV	Setzt Umgebungsvariablen in deinem Workspace. Definiere sie auf die gleiche Weise wie bei der Verwendung von dotenv in einem Node.js-Projekt. Details siehe https://www.npmjs.com/package/dotenv.
DEPLOYMENT_LINK_TYPE	Steuert das Format des Deployment-Links, der im Merge Request 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. Standard: dev-domain.
SHARED_VAULT_NAME	Name eines Shared Vaults der Resource Group, der mit dem Workspace verknüpft werden soll. Wenn gesetzt, verwendet das Preview Deployment die Secrets des Vaults, anstatt einen eigenen isolierten Satz zu pflegen. Der Shared Vault muss bereits in der Resource Group konfiguriert sein. Siehe Secret Management → Shared Vaults.
CI_PROFILE	Name des CI-Profils, das für das Deployment verwendet werden soll. Standardmäßig wird die ci.yml des Repositories verwendet.
CODESPHERE_RESTRICTED	Bei true ist die Development-Domain des Workspace nur für Mitglieder der Resource Group erreichbar, anstatt öffentlich zu sein. Standard: false.
CODESPHERE_BASE_IMAGE	Überschreibt das Base-Image, aus dem der Workspace erstellt wird. Standardmäßig wird das Standard-Image des Plans verwendet.
VPN_CONFIG	Falls du eine VPN-Konfiguration für diese Resource Group erstellt hast, kannst du sie hier über ihren Konfigurationsnamen referenzieren. Dadurch wird das Preview Deployment mit dieser VPN-Verbindung verknüpft.
GIT_CLONE_DEPTH	Shallow-Clone-Tiefe, die beim Auschecken des Repositories verwendet wird. Standardmäßig wird die vollständige Historie geladen.
GIT_SKIP_LFS	Bei true wird das Herunterladen (Smudging) von Git-LFS-Dateien beim Klonen übersprungen. Standard: false.
GIT_RECURSE_SUBMODULES	Bei false werden Submodule nicht initialisiert und geklont. Standard: true.
TLS_ALLOW_UNAUTHORIZED	Bei true wird die TLS-Zertifikatsprüfung bei der Kommunikation mit der Codesphere-API deaktiviert. Verwende dies nur für selbst gehostete Instanzen mit selbstsignierten Zertifikaten. Standard: false.

Phase 4: Deployment & Verifizierung

9. Committe und pushe die Datei .gitlab-ci.yml.
10. Öffne einen neuen Merge Request in deinem Repository.
11. Prüfe den Kommentarbereich deines Merge Requests.
    • Erfolg: Codesphere postet automatisch einen Kommentar mit dem direkten Link zu deinem neuen Preview Deployment.