So Richten Sie eine Salesforce-CI/CD-Pipeline mit GitHub Actions Ein

Um eine Salesforce-CI/CD-Pipeline mit GitHub Actions einzurichten, speichern Sie Ihre Metadaten im Source Format in Git, authentifizieren GitHub per JWT-basierter Connected App bei Ihrer Org und fügen einen Workflow hinzu, der Änderungen bei jedem Pull Request validiert und sie beim Merge deployt. Die gesamte Pipeline steckt in einer einzigen .github/workflows-YAML-Datei und läuft auf der Salesforce CLI. Diese Anleitung geht den aktuellen sf-v2-Weg durch und markiert danach die Teile, die in der Produktion still kaputtgehen. Sie ist Teil unserer SF-Guides-Bibliothek unter /serpent/resources.

Was brauchen Sie, bevor Sie starten?

Eine funktionierende Pipeline setzt voraus, dass ein paar Dinge bereits stehen:

• Projekt im Source Format. Ihre Metadaten liegen unter force-app im Source Format, committet in ein GitHub-Repo.
• Salesforce CLI v2 (sf). Die alte sfdx-CLI ist abgekündigt, bauen Sie also auf sf.
• Ein Deployment-Ziel. Eine Sandbox zur Validierung und eine Produktions- oder Staging-Org für das Release.
• Eine Connected App in der Ziel-Org mit aktivierten digitalen Signaturen sowie einem vorautorisierten Integrationsbenutzer.

Wenn Ihre Metadaten noch nicht in Git liegen, kommt diese Migration zuerst. Die Branching- und Umgebungsmechanik behandeln wir in unserem begleitenden Leitfaden zum Aufbau einer Salesforce-CI/CD-Pipeline mit GitHub Actions.

Wie verbinden Sie GitHub Actions sicher mit Salesforce?

Nutzen Sie den JWT Bearer Flow. Er ist headless, braucht kein interaktives Login und ist das, was Salesforce für CI empfiehlt. Erzeugen Sie ein Schlüsselpaar, laden Sie das Zertifikat in eine Connected App und melden Sie sich dann vom Runner mit dem privaten Schlüssel an.

1. Erstellen Sie Schlüssel und Zertifikat: openssl genrsa -out server.key 2048 und dann openssl req -new -x509 -nodes -sha256 -days 365 -key server.key -out server.crt.
2. Erstellen Sie eine Connected App in der Org, aktivieren Sie Use digital signatures und laden Sie server.crt hoch.
3. Speichern Sie server.key sowie Ihren Consumer Key, Benutzernamen und die Instance-URL als GitHub-Repository-Secrets, niemals im YAML.
4. Authentifizieren Sie auf dem Runner: sf org login jwt --client-id $SF_CONSUMER_KEY --jwt-key-file server.key --username $SF_USERNAME --instance-url $SF_INSTANCE_URL --set-default-org.

Wie sieht der GitHub-Actions-Workflow aus?

Das Kernmuster ist ein Workflow mit zwei Verhalten, abhängig vom Event. Validieren Sie bei einem Pull Request, damit nichts gemergt wird, das fehlschlagen würde; deployen Sie echt, wenn die Änderung auf Ihrem main-Branch landet.

• Trigger: pull_request gegen main zur Validierung, push auf main zum Deployment.
• Validierungsschritt (PR): sf project deploy validate --source-dir force-app --test-level RunLocalTests --wait 30 --verbose. Das ist ein Check-only-Lauf, es wird also nichts in die Org geschrieben.
• Deploy-Schritt (Merge): sf project deploy start --source-dir force-app --test-level RunLocalTests --wait 30 --verbose.

Nutzen Sie eine if:-Bedingung an jedem Job, damit dieselbe Datei beide Events abdeckt. Lokale Tests bei der Validierung zu fahren, macht daraus ein echtes Gate statt eines Stempels, und es ist das Rückgrat jeder ernsthaften Salesforce-Testautomatisierungs-Pipeline in CI.

Wie deployen Sie nur, was sich geändert hat?

Das gesamte force-app-Verzeichnis jedes Mal zu deployen ist langsam und wird schlimmer, je größer das Repo wird. Das Community-Tool sfdx-git-delta berechnet die Differenz zwischen zwei Commits und erzeugt ein Paket mit nur den geänderten Metadaten:

sf sgd source delta --to HEAD --from HEAD~1 --output delta --generate-delta --source-dir force-app

Sie richten den Deploy-Befehl dann auf das Delta-Verzeichnis. Das senkt die Deploy-Zeit deutlich, aber lesen Sie den nächsten Abschnitt, bevor Sie ihm blind vertrauen.

Was macht eine selbstgebaute Pipeline still kaputt?

Die meisten Tutorials enden bei einem grünen Deploy. Die Fehler tauchen später auf, und sie sind der Grund, warum wir Tooling darum herum bauen, statt Teams eine nackte YAML-Datei zu überlassen:

• Löschungen. Ein naives Delta deployt Ergänzungen und Änderungen, entfernt aber keine gelöschten Komponenten. Sie brauchen einen Destructive-Changes-Schritt, sonst driften die Metadaten und veraltete Komponenten häufen sich an.
• Partielle Metadaten. Profiles, Permission Sets und einige andere Typen leben weiterhin in großen, gemeinsam genutzten Dateien, die nicht sauber diffen, sodass Delta-Deployments sie verpassen oder überschreiben können.
• Die Wartung gehört Ihnen. Jede CLI-Änderung, jeder neue Metadatentyp und jeder Edge Case ist nun das YAML Ihres Teams zum Reparieren. Diese Kosten summieren sich, und genau das macht Back-Promotion zwischen Umgebungen schlimmer, wenn Sie es von Hand skripten.

Wenn Sie diese Pipeline nicht für immer besitzen möchten, übernimmt eine verwaltete Plattform Delta, Destructive Changes und die partiellen Metadaten-Kanten für Sie. Sehen Sie, was Serpent abdeckt und was es kostet, bevor Sie ein Quartal Engineering-Zeit in eine Eigenbau-Lösung stecken.

FAQ

Soll ich sfdx oder sf für eine Salesforce-GitHub-Actions-Pipeline nutzen?

Nutzen Sie sf (Salesforce CLI v2). Die alte sfdx-CLI ist abgekündigt und sollte nicht die Basis einer neuen Pipeline sein.

Warum JWT-Auth statt Benutzername und Passwort?

Der JWT Bearer Flow ist headless und braucht kein interaktives Login und keine MFA-Abfrage, was ein CI-Runner benötigt, und Salesforce empfiehlt ihn für Automatisierung.

Was ist der Unterschied zwischen deploy validate und deploy start?

Validate ist ein Check-only-Lauf, der prüft und Tests ausführt, ohne die Org zu ändern, ideal bei Pull Requests; start führt beim Merge das tatsächliche Deployment aus.

Brauche ich sfdx-git-delta?

Nein, aber es lohnt sich, sobald Deploys langsam werden. Kombinieren Sie es nur mit einem Destructive-Changes-Schritt, damit Löschungen behandelt und nicht still übersprungen werden.