FirstSales in CI/CD & Skripten verwenden

Führen Sie die FirstSales-CLI in Pipelines aus — maskierte Secrets, Fail-Fast-Authentifizierung, Dry-Run bei PRs und Apply auf main, idempotente Schritte und abgesicherte destruktive Aktionen.

8 Min. Lesezeit·Experte·7 Schritte

1
Die CLI in Pipelines bevorzugen
Für CI/CD-Jobs und lokale Skripte empfehlen die Docs die CLI gegenüber rohem HTTP — sie zentralisiert das Credential-Handling, gibt stabiles JSON aus, das Ihre Schritte parsen können, und behält die destruktiven Sicherungen, die Sie in der Automatisierung wollen. Ein Tool, ein Auth-Pfad, konsistente Ausgabe.
2
Den Key als maskiertes Secret injizieren
Speichern Sie Ihren Developer-API-Key im Secret-Store Ihres CI-Anbieters (GitHub-Actions-Secrets, GitLab-CI-Variablen usw.) und stellen Sie ihn als FIRSTSALES_API_KEY bereit. Hardcoden Sie ihn niemals in der Workflow-Datei. Die meisten CI-Systeme maskieren Secret-Werte automatisch in Logs — behalten Sie das bei, indem Sie den Key niemals echoen.
```
# GitHub Actions job step
- name: FirstSales sync
  env:
    FIRSTSALES_API_KEY: ${{ secrets.FIRSTSALES_API_KEY }}
  run: |
    npm install -g @firstsales.io/cli
    firstsales whoami --json
```
3
Bei ungültigem Key sofort fehlschlagen
Beginnen Sie jeden Job mit whoami, damit die Pipeline sofort stoppt, wenn der Key falsch oder widerrufen ist, statt einen Sync halb auszuführen:
```
firstsales whoami --json > /dev/null || {
  echo "FirstSales auth failed"; exit 1;
}
```

Mit --dry-run planen, dann anwenden

In der Automatisierung wollen Sie eine Vorschau, bevor Sie schreiben. Sichern Sie echte Mutationen hinter einem Plan-Schritt mit --dry-run ab (z. B. bei Pull Requests) und wenden Sie sie nur auf dem Main-Branch an:

# PR / plan: preview only
firstsales contacts create --org "$ORG" --workspace "$WS" \
  --data-file ./new-lead.json --dry-run

# main / apply: real write, idempotent
firstsales contacts create --org "$ORG" --workspace "$WS" \
  --data-file ./new-lead.json \
  --idempotency-key "lead-${GITHUB_SHA}"

5
Wiederholbare Schritte idempotent machen
CI-Schritte werden wiederholt — durch instabile Runner, durch Menschen, die einen Job erneut ausführen. Leiten Sie einen --idempotency-key aus etwas Stabilem ab (ein Commit-SHA, eine Zeilen-ID, eine Run-Nummer), damit ein erneuter Lauf nicht doppelt anlegt:
```
firstsales contact-imports create --org "$ORG" --workspace "$WS" \
  --data-file ./import.json \
  --idempotency-key "import-${CI_PIPELINE_ID}"
```
6
Destruktive Schritte absichern
Deletes erfordern --confirm, was in einer Pipeline genau richtig ist: Ein Cleanup-Job kann Daten nur entfernen, wenn das Flag explizit gesetzt ist. Halten Sie --confirm aus jedem Schritt heraus, der nicht löschen soll, und parsen Sie die --json-Ausgabe, um das Ergebnis zu verifizieren:
```
firstsales connectors delete --org "$ORG" --workspace "$WS" \
  --connector "$STALE_ID" --confirm --json | jq -e '.deleted == true'
```
7
JSON parsen, nicht scrapen
Die gesamte Ausgabe ist standardmäßig JSON — leiten Sie sie an jq weiter, um Entscheidungen zu treffen, Job-Outputs zu setzen oder spätere Schritte zu gaten. Scrapen Sie niemals die App-UI oder rufen Sie private Endpoints aus CI auf; wenn ein Befehl unsupported_operation zurückgibt, lassen Sie den Schritt fehlschlagen und melden Sie es, statt einen Workaround zu suchen.

Profi-Tipps

Hart erarbeitete Abkürzungen, damit die Aufwärmung auf Kurs bleibt.

whoami als erster Job-Schritt

Eine einzeilige Auth-Prüfung am Anfang des Jobs verwandelt einen falschen/abgelaufenen Key in einen sofortigen, offensichtlichen Fehler statt in einen teilweisen, verwirrenden.

Idempotency-Keys aus CI-Variablen ableiten

Commit-SHA, Pipeline-ID, Run-Nummer — jeder stabile Wert pro Lauf macht einen wiederholten Schritt zu einem sicheren No-op. Verwenden Sie niemals einen Zeitstempel oder Zufallswert; die untergraben den Zweck.

Zweiphasig: dry-run bei PRs, apply auf main

Spiegelt Infrastructure-as-Code. --dry-run bei Pull Requests zeigt den Diff zur Review; die echte Schreibaktion läuft erst nach dem Merge. Günstige Absicherung für irreversible Aktionen.

Auf der JSON-Ausgabe asserten

Leiten Sie --json an jq -e weiter, damit der Schritt tatsächlich fehlschlägt, wenn das Ergebnis nicht dem erwarteten entspricht, statt mit Exit-Code 0 bei einem stillen Fehler zu enden.

Häufig gestellte Fragen

Sollte CI die CLI oder die API verwenden?

Die CLI. Für CI/CD und Skripte wird sie gegenüber rohem HTTP empfohlen, weil sie das Credential-Handling und die Ausgabe standardisiert und die eingebauten Sicherungen für destruktive Operationen beibehält.

Wie handhabe ich den API-Key in CI?

Legen Sie ihn im Secret-Store Ihres CI-Anbieters ab und stellen Sie ihn als FIRSTSALES_API_KEY bereit. Hardcoden Sie ihn nicht in den Workflow und echoen Sie ihn niemals — die meisten CI-Systeme maskieren Secrets in Logs nur, wenn Sie sie nicht selbst ausgeben.

Wie kann ich eine Änderung vorab ansehen, bevor sie läuft?

Nutzen Sie --dry-run, um den Request auszugeben, ohne ihn zu senden. Ein gängiges Muster ist Dry-Run bei Pull Requests und die echte Schreibaktion nur auf dem Main-Branch.

Wie mache ich einen Schritt sicher wiederholbar?

Übergeben Sie --idempotency-key, abgeleitet aus einem stabilen Wert wie dem Commit-SHA oder der Pipeline-ID. Ein wiederholter Schritt mit demselben Key ist ein No-op statt eines doppelten Schreibvorgangs.

Wie verhindere ich, dass ein Cleanup-Job zu viel löscht?

Deletes erfordern --confirm, sodass ein Schritt nur Daten entfernen kann, wenn das Flag explizit gesetzt ist. Halten Sie es aus nicht-destruktiven Schritten heraus und asserten Sie mit jq -e auf dem --json-Ergebnis.

Kann ich Entscheidungen aus der Ausgabe treffen?

Ja — die Ausgabe ist standardmäßig JSON. Leiten Sie sie an jq weiter, um spätere Schritte zu gaten oder Job-Outputs zu setzen. Scrapen Sie nicht die UI; melden Sie den Schritt bei unsupported_operation als fehlgeschlagen.

Bereit, das in die Praxis umzusetzen?

Starten Sie Ihre FirstSales-Testphase und richten Sie in wenigen Minuten ein aufgewärmtes, authentifiziertes Postfach ein.

Für 1 $ starten

Alle Tutorials

FirstSales in CI/CD & Skripten verwenden

Die CLI in Pipelines bevorzugen

Den Key als maskiertes Secret injizieren

Bei ungültigem Key sofort fehlschlagen