Zum Hauptinhalt springen
Version: Weekly Build

Gitlab Preview Deployment

Phase 1: Vorbereitung des Accounts​

  1. Lege ein Passwort für dein Codesphere-Konto fest (erforderlich für den API-Zugriff).
    • Hinweis: Falls du dich über Google/GitHub angemeldet hast, nutze den Link „Passwort vergessen“, um ein eigenständiges Passwort festzulegen.
  2. Verbinde dein GitLab-Konto mit Codesphere.
    • Aktion: Klicke auf „+ New Workspace“ und wähle „Connect GitLab“, um die Autorisierung durchzuführen.
  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​

  1. Öffne dein Repository in GitLab.
  2. Navigiere zu Settings > CI/CD > Variables.
  3. Füge die folgenden Variablen hinzu (entferne den Haken bei „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​

  1. Erstelle eine .gitlab-ci.yml-Datei im Root-Verzeichnis deines Repositories.
  2. 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
    TEAM: 'My Team'       # REPLACE with your exact Team 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 team 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 team 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 team 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 verbindet einen bestehenden Team Shared Vault mit dem Preview Deployment, sodass dessen Secrets wiederverwendet werden, anstatt einen eigenen isolierten Satz zu pflegen. Der Shared Vault muss bereits im Team 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.

VariableVerwendung
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_TOKENEmpfohlen. Dein Codesphere API-Token, generiert unter Account Settings > API Keys. Wenn diese Variable gesetzt ist, werden EMAIL und PASSWORD ignoriert.
EMAIL(Veraltet) E-Mail-Adresse des Codesphere-Benutzers. Verwende stattdessen API_TOKEN.
PASSWORD(Veraltet) Passwort des Codesphere-Benutzers. Verwende stattdessen API_TOKEN.
TEAM (*)Name des Codesphere-Teams.
PLANWorkspace-Plan des zu erstellenden Workspace. Verfügbare Optionen: Micro, Boost, Pro. Standard: Boost.
ON_DEMANDLegt fest, ob dieses Preview Deployment im Always-on- oder im Off-when-unused-Deployment-Modus bereitgestellt werden soll. Verfügbare Optionen: true, false.
ENVSetzt Umgebungsvariablen in deinem Workspace. Definiere sie auf dieselbe Weise wie bei der Verwendung von dotenv in einem Node.js-Projekt. Details siehe https://www.npmjs.com/package/dotenv.
DEPLOYMENT_LINK_TYPESteuert 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_NAMEName eines Team Shared Vaults, der mit dem Workspace verbunden werden soll. Wenn gesetzt, verwendet das Preview Deployment die Secrets des Vaults, anstatt einen eigenen isolierten Satz zu pflegen. Der Shared Vault muss bereits im Team konfiguriert sein. Siehe Secret Management → Shared Vaults.
CI_PROFILEName des CI-Profils, das für das Deployment verwendet werden soll. Standardmäßig wird die ci.yml des Repositories verwendet.
CODESPHERE_RESTRICTEDWenn true, ist die Development-Domain des Workspace nur für Teammitglieder 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_CONFIGFalls für dieses Team eine VPN-Konfiguration erstellt wurde, kann sie hier über ihren Konfigurationsnamen referenziert werden. Dadurch wird das Preview Deployment mit dieser VPN-Verbindung verknüpft.
GIT_CLONE_DEPTHShallow-Clone-Tiefe, die beim Auschecken des Repositories verwendet wird. Standardmäßig wird die vollständige Historie geklont.
GIT_SKIP_LFSWenn true, wird das Herunterladen (Smudging) von Git-LFS-Dateien beim Klonen übersprungen. Standard: false.
GIT_RECURSE_SUBMODULESWenn false, werden Submodule nicht initialisiert und geklont. Standard: true.
TLS_ALLOW_UNAUTHORIZEDWenn true, wird die TLS-Zertifikatsprüfung bei der Kommunikation mit der Codesphere-API deaktiviert. Dies sollte nur bei selbst gehosteten Instanzen mit selbstsignierten Zertifikaten verwendet werden. Standard: false.

Phase 4: Deployment & Überprüfung​

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