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 gemerged werden.
Voraussetzungen
Bevor ihr die Automatisierung einrichtet, stellt sicher, dass Folgendes vorhanden ist:
- Codesphere-Account
- Admin-Zugriff auf das Bitbucket-Repository, das ihr verbinden möchtet
Zukünftige API-Unterstützung
Wir arbeiten derzeit an einem dedizierten API-Token-System. Sobald dieses veröffentlicht ist, könnt ihr euch mit Tokens anstelle von Account-Passwörtern authentifizieren.
Empfohlen: Verwendung eines Service-Accounts
Für Produktionsumgebungen empfehlen wir dringend die Verwendung eines Service-Accounts (eines dedizierten Maschinenbenutzers) anstelle eines persönlichen Entwickler-Accounts. Dies verhindert, dass die Automatisierung nicht mehr funktioniert, wenn ein Teammitglied das Unternehmen verlässt.
- Service-Account erstellen: Registriert einen neuen Codesphere-Account mit einem dedizierten E-Mail-Alias, z. B.
[email protected]. - Zum Team einladen: Meldet euch mit eurem Haupt-Codesphere-Account an und ladet diesen neuen Service-Account zu eurem Ziel-Team ein.
- Bitbucket verbinden: Meldet euch als Service-Account an und stellt sicher, dass dieser die notwendigen Berechtigungen hat, um auf euer Bitbucket-Repository zuzugreifen.
- Passwort festlegen: Da OAuth für die Automatisierung nicht verwendet werden kann, stellt sicher, dass für diesen Service-Account ein Passwort gesetzt ist (nutzt den "Passwort vergessen"-Ablauf, falls ihr euch über Bitbucket/Google registriert habt).
Wichtig: Passwort-Anforderung
Bitbucket erfordert einen Standard-Login mit E-Mail/Passwort. Wenn euer Service-Account über OAuth erstellt wurde, müsst ihr ein Passwort festlegen:
- 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.
Einrichtung von Preview Deployments
- Falls noch nicht geschehen, erstellt einen Codesphere-Benutzer mit Benutzername & Passwort (OAuth funktioniert nicht bei der Nutzung von Bitbucket Pipelines) – wir empfehlen, hierfür einen separaten Sysadmin-Benutzer anzulegen.
- Meldet euch mit eurem neuen Benutzer an und verbindet ihn mit Bitbucket, indem ihr auf den Button "+ Create Workspace" klickt
und im Modal "Create Workspace" "Go to Bitbucket Login" auswählt.
Nach dem Anmelden könnt ihr aus euren verfügbaren Repositories auswählen.
- Stellt sicher, dass der verbundene Bitbucket-Account Zugriff auf das Repository hat, für das ihr die Preview Deployments einrichten möchtet.
- Stellt sicher, dass das Repository eine Codesphere CI Pipeline mit Anweisungen enthält, wie eure App gebaut und ausgeführt wird, die eure Pipeline anschließend nutzen kann, um euer Preview Deployment zu erstellen.
- Aktiviert Pipelines für euren Bitbucket-Account (erfordert eingerichtete 2FA).
- Erstellt einen Bitbucket-Access-Token mit Lese- und Schreibzugriff auf das Repository und die Pull Requests.
- Navigiert zu den Repository-Einstellungen > Pipelines > Repository Variables und fügt den Umgebungsvariablen des Repositories folgende Secrets hinzu – achtet darauf, die Checkbox für "secured" zu aktivieren. Weitere Informationen dazu, welche Variablen gesetzt werden können, findet ihr unten.
- Erstellt eine
bitbucket-pipelines.yml-Datei im 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:
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
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
Die folgenden Variablen könnt ihr für eure Repository-Variablen verwenden.
(*) = erforderliche Variable.
| Variable | Verwendung |
|---|---|
| ACCESS_TOKEN (*) | Der Access Token, den ihr für das Repository erstellt habt. Es wird empfohlen, eine sichere Repository-Variable zu verwenden. |
| EMAIL (*) | E-Mail-Adresse des Codesphere-Benutzers |
| PASSWORD (*) | Passwort des Codesphere-Benutzers. Es wird empfohlen, eine sichere Repository-/Workspace-Variable zu verwenden. |
| TEAM (*) | Name des Codesphere-Teams. |
| PLAN | Workspace-Plan des zu erstellenden Workspaces. Verfügbare Optionen: Micro, Boost, Pro. Standard: Boost. |
| ON_DEMAND | Legt fest, ob dieses Preview Deployment im Modus "always on" oder "off when unused" deployt werden soll. Verfügbare Optionen: true, false |
| ENV | Setzt Umgebungsvariablen in eurem Workspace. Definiert sie auf die gleiche Weise, wie ihr es bei der Verwendung von dotenv in einem Node.js-Projekt tun würdet. Details siehe https://www.npmjs.com/package/dotenv. |
| VPN_CONFIG | Falls 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. |
| DEPLOYMENT_LINK_TYPE | Steuert das Format des Deployment-Links, der im PR-Kommentar veröffentlicht 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 diese Anleitung befolgt habt, läuft eure Pipeline bei jedem Pull Request und erstellt ein Preview Deployment, mit 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.
