Bitbucket Preview Deployment
Diese Anleitung erklärt, wie automatisch ein Preview Codesphere Workspace für jeden Pull Request (PR) erstellt wird, der in eurem Bitbucket-Repository geöffnet wird. Dadurch kann euer Team Änderungen in einer Live-Umgebung überprüfen, bevor sie gemergt werden.
Voraussetzungen
Bevor die Automation eingerichtet wird, sollte Folgendes bereit sein:
- Codesphere-Konto
- Admin-Zugriff auf das Bitbucket-Repository, das verbunden werden soll
Zukünftige API-Unterstützung
Aktuell wird an einem eigenen API-Token-System gearbeitet. Sobald dieses verfügbar ist, kann die Authentifizierung über Tokens statt über Kontopasswörter erfolgen.
Empfehlung: Verwendung eines Service Accounts
Für Produktionsumgebungen wird dringend empfohlen, einen Service Account (einen dedizierten Maschinen-Benutzer) anstelle eines persönlichen Entwicklerkontos zu verwenden. Dies verhindert, dass die Automation ausfällt, wenn ein Teammitglied das Unternehmen verlässt.
- Service Account erstellen: Registriert ein neues Codesphere-Konto mit einem dedizierten E-Mail-Alias, z. B.
[email protected]. - Zum Team einladen: Meldet euch mit eurem Haupt-Codesphere-Konto an und ladet diesen neuen Service Account in euer Ziel-Team ein.
- Bitbucket verbinden: Meldet euch als Service Account an und stellt sicher, dass dieser die notwendigen Berechtigungen für den Zugriff auf euer Bitbucket-Repository hat.
- Passwort festlegen: Da OAuth nicht für Automationen verwendet werden kann, muss für diesen Service Account ein Passwort gesetzt sein (nutzt den "Passwort vergessen"-Ablauf, falls die Registrierung über Bitbucket/Google erfolgt ist).
Wichtig: Passwort erforderlich
Bitbucket erfordert einen Standard-Login mit E-Mail/Passwort. Wurde der Service Account über OAuth erstellt, muss ein Passwort festgelegt werden:
- Meldet euch von Codesphere ab.
- Klickt auf dem Login-Bildschirm auf Passwort vergessen.
- Folgt den Anweisungen in der E-Mail, um ein Passwort für den Service Account festzulegen.
Einrichten von Preview Deployments
- Falls noch nicht geschehen, erstellt einen Codesphere-Benutzer mit Benutzername & Passwort (OAuth funktioniert nicht für die Nutzung von Bitbucket Pipelines) - wir empfehlen, dafür einen separaten Sysadmin-Benutzer anzulegen.
- Meldet euch mit eurem neuen Benutzer an und verbindet ihn mit Bitbucket, indem ihr auf die Schaltfläche "+ Create Workspace" klickt
und im "Create Workspace"-Modal "Go to Bitbucket Login" auswählt.
Nach der Anmeldung könnt ihr aus euren verfügbaren Repositories auswählen.
- Stellt sicher, dass das verbundene Bitbucket-Konto Zugriff auf das Repository hat, für das die Preview Deployments eingerichtet werden.
- Stellt sicher, dass das Repository eine Codesphere-CI-Pipeline mit Anweisungen zum Bauen & Ausführen eurer App enthält, die eure Pipeline anschließend zur Erstellung des Preview Deployments verwenden kann.
- Aktiviert Pipelines für euer Bitbucket-Konto (erfordert die Einrichtung von 2FA).
- Erstellt ein Bitbucket-Zugriffstoken mit Lese- und Schreibzugriff auf das Repository und Pull Requests.
- Navigiert zu Settings > Pipelines > Repository Variables des Repositories und fügt die folgenden Secrets zu den Umgebungsvariablen des Repositories hinzu - achtet darauf, das Kontrollkästchen für "secured" zu aktivieren. Weitere Informationen dazu, welche Variablen gesetzt werden können, findet ihr unten.
- Erstellt eine Datei
bitbucket-pipelines.ymlim Root-Verzeichnis eures Repositories und fügt 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
EMAIL: $CODESPHERE_EMAIL
PASSWORD: $CODESPHERE_PASSWORD
TEAM: My Team
PLAN: Micro
DEPLOYMENT_LINK_TYPE: preview # or 'dev-domain'
VPN_CONFIG: vpnConfigName
SHARED_VAULT_NAME: sharedVaultName
ENV: |
testing=abc
Ihr könnt eure Pipeline so konfigurieren, dass sie andere Trigger als nur Pull Requests hat. Weitere Informationen zu den verfügbaren Pipeline-Einstellungen von Bitbucket findet ihr hier.
Verfügbare Variablen
Im Folgenden sind die Variablen aufgeführt, die ihr für eure Repository-Variablen verwenden könnt.
(*) = erforderliche Variable.
| Variable | Verwendung |
|---|---|
| API_URL (*) | Die Basis-URL für eure Codesphere-Instanz einschließlich https:// z. B. https://cloud.codesphere.com |
| ACCESS_TOKEN (*) | Das Zugriffstoken, das ihr für das Repository erstellt habt. Es wird empfohlen, eine gesicherte Repository-Variable zu verwenden. |
| EMAIL (*) | E-Mail des Codesphere-Benutzers |
| PASSWORD (*) | Passwort des Codesphere-Benutzers. Es wird empfohlen, eine gesicherte Repository-/Workspace-Variable zu verwenden. |
| 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 | Setzt Umgebungsvariablen in eurem Workspace. Definiert sie auf die gleiche Weise wie bei der Verwendung von dotenv in einem Node.js-Projekt. Details siehe https://www.npmjs.com/package/dotenv. |
| VPN_CONFIG | Wenn ihr für dieses Team eine VPN-Konfiguration erstellt habt, könnt ihr sie hier über ihren Konfigurationsnamen referenzieren. Dadurch werden erstellte Preview Deployments mit dieser VPN-Verbindung verbunden. |
| SHARED_VAULT_NAME | Wenn ihr für dieses Team einen Shared Vault erstellt habt, könnt ihr ihn hier über seinen Namen referenzieren. 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 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 zur Development-Domain des Workspace. Standard: dev-domain. |
Zusätzliche Informationen
Nachdem ihr dieser Anleitung gefolgt seid, läuft eure Pipeline bei jedem Pull Request und erstellt ein Preview Deployment, in dem ihr eure Änderungen überprüfen könnt. Dabei wird ein neuer Kommentar zu eurem Pull Request hinzugefügt, der die Domain zu eurem Preview Deployment enthält.
