Bitbucket Preview Deployment

Diese Anleitung erklärt, wie automatisch ein Preview Codesphere Workspace für jeden Pull Request (PR) erstellt wird, der in deinem Bitbucket-Repository geöffnet wird. Dies ermöglicht es deinem Team, Änderungen in einer Live-Umgebung zu überprüfen, bevor sie gemerged werden.

Voraussetzungen

Bevor die Automatisierung eingerichtet wird, stelle sicher, dass Folgendes bereit ist:

• Codesphere Account
• Admin-Zugriff auf das Bitbucket-Repository, das verbunden werden soll

Empfehlung: Verwendung eines Service Accounts

Für Produktionsumgebungen wird dringend empfohlen, einen Service Account (einen dedizierten Maschinen-Benutzer) anstelle eines persönlichen Entwickler-Accounts zu verwenden. Dies verhindert, dass die Automatisierung ausfällt, wenn ein Teammitglied das Unternehmen verlässt.

1. Service Account erstellen: Registriere ein neues Codesphere-Konto mit einem dedizierten E-Mail-Alias, z. B. [email protected].
2. Zur Resource Group einladen: Melde dich bei deinem Haupt-Codesphere-Konto an und lade diesen neuen Service Account zu deiner Ziel-Resource Group ein.
3. Bitbucket verbinden: Melde dich als Service Account an und stelle sicher, dass er die notwendigen Berechtigungen hat, um auf dein Bitbucket-Repository zuzugreifen.
4. API-Token generieren: Gehe in Codesphere zu Account Settings > API Keys und erstelle ein neues Token für diesen Service Account. Speichere es als Bitbucket-Repository-Variable (siehe unten).

Veraltet: E-Mail/Passwort-Authentifizierung

Die Authentifizierung mit EMAIL und PASSWORD ist veraltet. Verwende stattdessen API_TOKEN. Die alten Variablen funktionieren weiterhin, geben aber bei jedem Pipeline-Lauf eine Deprecation-Warnung aus.

Einrichtung von Preview Deployments

1. Falls noch nicht geschehen, erstelle einen Codesphere-Benutzer mit Benutzername & Passwort (OAuth funktioniert nicht für die Verwendung von Bitbucket Pipelines) – wir empfehlen, dafür einen separaten Sysadmin-Benutzer anzulegen.
   
2. Melde dich mit deinem neuen Benutzer an und verbinde ihn mit Bitbucket, indem du auf den Button "+ Create Workspace" klickst
   
   

und im "Create Workspace"-Modal "Go to Bitbucket Login" auswählst.

Nach der Anmeldung kannst du aus deinen verfügbaren Repositories auswählen.

3. Stelle sicher, dass das verbundene Bitbucket-Konto Zugriff auf das Repository hat, für das die Preview Deployments eingerichtet werden.
4. Stelle sicher, dass das Repository eine Codesphere CI Pipeline mit Anweisungen zum Bauen & Ausführen deiner App enthält, die deine Pipeline dann verwenden kann, um dein Preview Deployment zu erstellen.
5. Aktiviere Pipelines für dein Bitbucket-Konto (erfordert eingerichtete 2FA).
6. Erstelle ein Bitbucket Access Token mit Lese- und Schreibzugriff auf das Repo und Pull Requests.

7. Navigiere zu den Repository-Settings > Pipelines > Repository Variables und füge die folgenden Secrets zu den Umgebungsvariablen des Repositories hinzu – achte darauf, die Checkbox für "secured" zu setzen. Weitere Informationen dazu, welche Variablen gesetzt werden können, findest du unten.

8. Erstelle eine Datei bitbucket-pipelines.yml im Root-Verzeichnis deines Repositories und füge folgenden Code hinzu:

image: atlassian/default-image:3

pipelines:
  pull-requests:
    '**':
      - step:
          deployment: Test
          script:
            - pipe: docker://ghcr.io/codesphere-cloud/codesphere-monorepo/integrations/bitbucket-ci:latest
              variables:
                API_URL: https://cloud.codesphere.com # replace with your instance URL
                ACCESS_TOKEN: $ACCESS_TOKEN
                API_TOKEN: $CODESPHERE_API_TOKEN
                RESOURCE_GROUP: My Resource Group
                PLAN: Micro
                DEPLOYMENT_LINK_TYPE: preview  # or 'dev-domain'
                VPN_CONFIG: vpnConfigName
                SHARED_VAULT_NAME: sharedVaultName
                CI_PROFILE: my-ci-profile
                CODESPHERE_RESTRICTED: 'false'
                CODESPHERE_BASE_IMAGE: my-base-image
                GIT_CLONE_DEPTH: '1'
                GIT_SKIP_LFS: 'false'
                GIT_RECURSE_SUBMODULES: 'true'
                TLS_ALLOW_UNAUTHORIZED: 'false'
                ENV: |
                    testing=abc

Du kannst deine Pipeline so konfigurieren, dass sie andere Trigger als nur Pull Requests hat. Weitere Informationen zu den verfügbaren Pipeline-Einstellungen von Bitbucket findest du hier.

Verfügbare Variablen

Im Folgenden sind die Variablen aufgeführt, die du für deine Repository-Variablen verwenden kannst. (*) = erforderliche Variable.

Variable	Verwendung
API_URL (*)	Die Basis-URL deiner Codesphere-Instanz inklusive https:// z. B. https://cloud.codesphere.com
ACCESS_TOKEN (*)	Das Access Token, das du für das Repository erstellt hast. Es wird empfohlen, eine gesicherte Repository-Variable zu verwenden.
API_TOKEN	Empfohlen. Dein Codesphere API-Token, generiert unter Account Settings > API Keys. Wenn gesetzt, werden EMAIL und PASSWORD ignoriert.
EMAIL	(Veraltet) E-Mail des Codesphere-Benutzers. Verwende stattdessen API_TOKEN.
PASSWORD	(Veraltet) Passwort des Codesphere-Benutzers. 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 immer eingeschaltet (always on) oder bei Nichtnutzung ausgeschaltet (off when unused) bereitgestellt werden soll. Verfügbare Optionen: true, false
ENV	Setzt Umgebungsvariablen in deinem Workspace. Definiere sie auf die gleiche Weise, wie du es bei der Verwendung von dotenv in einem Node.js-Projekt tun würdest. Details siehe https://www.npmjs.com/package/dotenv.
VPN_CONFIG	Wenn du eine VPN-Konfiguration für diese Resource Group erstellt hast, kannst du hier über den Konfigurationsnamen darauf verweisen. Dadurch werden erstellte Preview Deployments mit dieser VPN-Verbindung verbunden.
SHARED_VAULT_NAME	Wenn du einen Shared Vault für diese Resource Group erstellt hast, kannst du hier über seinen Namen darauf verweisen. Preview Deployments verwenden dann die Secrets des Vaults wieder, anstatt einen eigenen isolierten Satz zu pflegen, sodass Secrets einmal gepflegt und über alle Preview Deployments hinweg geteilt werden können. Der Shared Vault muss bereits in der Resource Group konfiguriert sein. Siehe Secret Management → Shared Vaults.
DEPLOYMENT_LINK_TYPE	Steuert das Format des Deployment-Links, der im PR-Kommentar 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.
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	Wenn true, ist die Dev-Domain des Workspace nur für Mitglieder der Resource Group erreichbar, anstatt öffentlich zu sein. Standard: false.
CODESPHERE_BASE_IMAGE	Überschreibt das Basis-Image, aus dem der Workspace erstellt wird. Standardmäßig wird das Standard-Image des Plans verwendet.
GIT_CLONE_DEPTH	Shallow-Clone-Tiefe, die beim Auschecken des Repositories verwendet wird. Standardmäßig wird die vollständige Historie verwendet.
GIT_SKIP_LFS	Wenn true, wird das Herunterladen (Smudging) von Git-LFS-Dateien beim Klonen übersprungen. Standard: false.
GIT_RECURSE_SUBMODULES	Wenn false, werden Submodule nicht initialisiert und geklont. Standard: true.
TLS_ALLOW_UNAUTHORIZED	Wenn 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.

Zusätzliche Informationen

Nach dem Befolgen dieser Anleitung läuft deine Pipeline bei jedem Pull Request und erstellt ein Preview Deployment, mit dem du deine Änderungen überprüfen kannst. Es wird ein neuer Kommentar zu deinem Pull Request hinzugefügt, der die Domain zu deinem Preview Deployment enthält.