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. So kann dein Team Änderungen in einer Live-Umgebung überprüfen, bevor sie gemerged werden.
Voraussetzungen
Bevor die Automatisierung eingerichtet wird, stelle sicher, dass Folgendes vorhanden ist:
- Codesphere-Konto
- Admin-Zugriff auf das Bitbucket-Repository, das verbunden werden soll
Empfohlen: Verwendung eines Service Accounts
Für Produktionsumgebungen wird dringend empfohlen, einen Service Account (einen dedizierten Maschinenbenutzer) anstelle eines persönlichen Entwicklerkontos zu verwenden. Dies verhindert, dass die Automatisierung unterbrochen wird, wenn ein Teammitglied das Unternehmen verlässt.
- Service Account erstellen: Registriere ein neues Codesphere-Konto mit einem dedizierten E-Mail-Alias, z. B.
[email protected]. - Zum Team einladen: Melde dich bei deinem Haupt-Codesphere-Konto an und lade diesen neuen Service Account zu deinem Ziel-Team ein.
- Bitbucket verbinden: Melde dich als Service Account an und stelle sicher, dass dieser die notwendigen Berechtigungen hat, um auf dein Bitbucket-Repository zuzugreifen.
- API-Token generieren: Gehe in Codesphere zu Account Settings > API Keys und erstelle einen neuen Token für diesen Service Account. Speichere ihn als Bitbucket Repository Variable (siehe unten).
Veraltet: Authentifizierung per E-Mail/Passwort
Die Authentifizierung mit EMAIL und PASSWORD ist veraltet. Verwende stattdessen API_TOKEN. Die alten Variablen funktionieren weiterhin, geben aber in deinem Pipeline-Lauf eine Warnung zur Veraltung aus.
Einrichten von Preview Deployments
- Falls noch nicht geschehen, erstelle einen Codesphere-Benutzer mit Benutzername & Passwort (OAuth funktioniert nicht bei der Verwendung von Bitbucket Pipelines) – wir empfehlen, hierfür einen separaten Sysadmin-Benutzer anzulegen.
- Melde dich mit deinem neuen Benutzer an und verbinde ihn mit Bitbucket, indem du auf die Schaltfläche "+ Create Workspace" klickst
und im Modal "Create Workspace" "Go to Bitbucket Login" auswählst.
Nach der Anmeldung kannst du aus deinen verfügbaren Repositories auswählen.
- Stelle sicher, dass das verbundene Bitbucket-Konto Zugriff auf das Repository hat, für das die Preview Deployments eingerichtet werden.
- 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.
- Aktiviere Pipelines für dein Bitbucket-Konto (erfordert eingerichtete 2FA).
- Erstelle ein Bitbucket-Zugriffstoken mit Lese- und Schreibzugriff auf das Repository und Pull Requests.
- Navigiere zu Settings > Pipelines > Repository Variables des Repositorys und füge die folgenden Secrets zu den Umgebungsvariablen des Repositorys hinzu – achte darauf, die Checkbox „secured“ zu aktivieren. Weitere Informationen dazu, welche Variablen gesetzt werden können, findest du unten.
- Erstelle eine
bitbucket-pipelines.yml-Datei im Root-Verzeichnis deines Repositorys und füge den 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
TEAM: My Team
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 Variables verwenden kannst.
(*) = erforderliche Variable.
| Variable | Verwendung |
|---|---|
| API_URL (*) | Die Basis-URL für deine Codesphere-Instanz einschließlich https://, z. B. https://cloud.codesphere.com |
| ACCESS_TOKEN (*) | Das Zugriffstoken, das du für das Repository erstellt hast. Es wird empfohlen, eine sichere Repository-Variable zu verwenden. |
| API_TOKEN | Empfohlen. Dein Codesphere-API-Token, generiert unter Account Settings > API Keys. Wenn gesetzt, werden EMAIL und PASSWORD ignoriert. |
(Veraltet) E-Mail des Codesphere-Benutzers. Verwende stattdessen API_TOKEN. | |
| PASSWORD | (Veraltet) Passwort des Codesphere-Benutzers. Verwende stattdessen API_TOKEN. |
| TEAM (*) | Name des Codesphere-Teams. |
| PLAN | Workspace-Plan des zu erstellenden Workspace. Verfügbare Optionen: Micro, Boost, Pro. Standard: Boost. |
| ON_DEMAND | Legt fest, ob dieses Preview Deployment im Modus „always on“ oder „off when unused“ bereitgestellt werden soll. Verfügbare Optionen: true, false |
| ENV | Setze 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. Siehe https://www.npmjs.com/package/dotenv für Details. |
| VPN_CONFIG | Wenn du für dieses Team eine VPN-Konfiguration erstellt hast, kannst du sie hier über ihren Konfigurationsnamen referenzieren. Dadurch werden erstellte Preview Deployments mit dieser VPN-Verbindung verbunden. |
| SHARED_VAULT_NAME | Wenn du für dieses Team einen Shared Vault erstellt hast, kannst du ihn hier über seinen Namen referenzieren. Preview Deployments verwenden dann die Secrets dieses 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 im Team 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 Entwicklungsdomain 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 Repositorys verwendet. |
| CODESPHERE_RESTRICTED | Wenn true, ist die Dev-Domain des Workspace nur für Teammitglieder 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 Repositorys 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
Nachdem du diese Anleitung befolgt hast, läuft deine Pipeline bei jedem Pull Request und erstellt ein Preview Deployment, mit dem du deine Änderungen überprüfen kannst. Sie fügt deinem Pull Request einen neuen Kommentar mit der Domain zu deinem Preview Deployment hinzu.
