NouveauDécouvrir comment
FirstSales
Accueil/Tutoriels/Utiliser FirstSales en CI/CD & scripts
Développeur & CLI

Utiliser FirstSales en CI/CD & scripts

Exécutez la CLI FirstSales dans vos pipelines — secrets masqués, authentification fail-fast, dry-run sur les PR et apply sur main, étapes idempotentes et actions destructrices protégées.

8 min de lecture·Avancé·7 étapes
  1. 1

    Privilégiez le CLI dans les pipelines

    Pour les jobs CI/CD et les scripts locaux, la documentation recommande le CLI plutôt que le HTTP brut — il centralise la gestion des identifiants, produit un JSON stable que vos étapes peuvent parser, et conserve les garde-fous sur les opérations destructrices dont vous avez besoin en automatisation. Un seul outil, un seul chemin d'authentification, une sortie cohérente.

  2. 2

    Injectez la clé comme secret masqué

    Stockez votre clé Developer API dans le gestionnaire de secrets de votre fournisseur CI (GitHub Actions secrets, variables GitLab CI, etc.) et exposez-la sous FIRSTSALES_API_KEY. Ne la codez jamais en dur dans le fichier de workflow. La plupart des systèmes CI masquent automatiquement les valeurs secrètes dans les logs — préservez cela en ne faisant jamais d'echo de la clé.

    # 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. 3

    Échouez rapidement en cas de mauvaise clé

    Démarrez chaque job avec whoami afin que le pipeline s'arrête immédiatement si la clé est incorrecte ou révoquée, plutôt que d'exécuter une synchronisation à moitié :

    firstsales whoami --json > /dev/null || {
  echo "FirstSales auth failed"; exit 1;
}
  4. 4

    Planifiez avec --dry-run, puis appliquez

    En automatisation, vous voulez une prévisualisation avant d'écrire. Bloquez les mutations réelles derrière une étape de planification avec --dry-run (par exemple sur les pull requests), et n'appliquez que sur la branche principale :

    # 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. 5

    Rendez les étapes réessayables idempotentes

    Les étapes CI sont retentées — par des runners instables, par des humains qui relancent un job. Dérivez une --idempotency-key à partir de quelque chose de stable (un SHA de commit, un ID de ligne, un numéro de run) pour qu'une relance ne crée pas de doublon :

    firstsales contact-imports create --org "$ORG" --workspace "$WS" \
  --data-file ./import.json \
  --idempotency-key "import-${CI_PIPELINE_ID}"
  6. 6

    Protégez les étapes destructrices

    Les suppressions exigent --confirm, ce qui est exactement ce que vous voulez dans un pipeline : un job de nettoyage ne peut supprimer des données que si le flag est explicitement présent. Gardez --confirm hors de toute étape qui ne devrait pas supprimer, et parsez la sortie --json pour vérifier le résultat :

    firstsales connectors delete --org "$ORG" --workspace "$WS" \
  --connector "$STALE_ID" --confirm --json | jq -e '.deleted == true'
  7. 7

    Parsez le JSON, ne faites pas de scraping

    Toute la sortie est en JSON par défaut — passez-la à jq pour prendre des décisions, définir des outputs de job, ou conditionner des étapes suivantes. Ne faites jamais de scraping de l'interface de l'app ni d'appel aux endpoints privés depuis la CI ; si une commande renvoie unsupported_operation, faites échouer l'étape et remontez l'erreur plutôt que de la contourner.

Astuces de pro

Des raccourcis chèrement acquis pour garder le préchauffage sur la bonne voie.

1

whoami comme première étape du job

Une vérification d'authentification d'une ligne en tête de job transforme une clé mauvaise/expirée en échec instantané et explicite plutôt qu'en résultat partiel et confus.

2

Dérivez les clés d'idempotence des variables CI

SHA de commit, ID de pipeline, numéro de run — toute valeur stable propre à chaque run rend une étape retentée sûre et sans effet de bord. N'utilisez jamais un horodatage ou une valeur aléatoire : cela va à l'encontre de l'objectif.

3

Deux phases : dry-run sur les PR, apply sur main

Reproduisez le modèle infra-as-code. --dry-run sur les pull requests montre le diff pour revue ; l'écriture réelle ne s'exécute qu'après le merge. Une protection peu coûteuse pour des actions irréversibles.

4

Vérifiez la sortie JSON par assertion

Passez --json à jq -e afin que l'étape échoue réellement quand le résultat n'est pas celui attendu, plutôt que de sortir en code 0 sur une erreur silencieuse.

Questions fréquentes

La CI doit-elle utiliser le CLI ou l'API ?

Le CLI. Pour la CI/CD et les scripts, il est recommandé au HTTP brut car il standardise la gestion des identifiants et de la sortie, et conserve les garde-fous intégrés sur les opérations destructrices.

Comment gérer la clé API en CI ?

Placez-la dans le gestionnaire de secrets de votre fournisseur CI et exposez-la sous FIRSTSALES_API_KEY. Ne la codez pas en dur dans le workflow, et ne faites jamais d'echo dessus — la plupart des systèmes CI ne masquent les secrets dans les logs que si vous ne les affichez pas vous-même.

Comment prévisualiser un changement avant qu'il ne s'exécute ?

Utilisez --dry-run pour afficher la requête sans l'envoyer. Un pattern courant est un dry-run sur les pull requests et l'écriture réelle uniquement sur la branche principale.

Comment rendre une étape sûre à relancer ?

Passez --idempotency-key dérivée d'une valeur stable comme le SHA de commit ou l'ID de pipeline. Une étape retentée avec la même clé devient un no-op plutôt qu'une écriture en double.

Comment empêcher un job de nettoyage de trop supprimer ?

Les suppressions exigent --confirm, si bien qu'une étape ne peut supprimer des données que si le flag est explicitement présent. Ne l'ajoutez pas aux étapes non destructrices, et vérifiez le résultat --json avec jq -e.

Puis-je prendre des décisions à partir de la sortie ?

Oui — la sortie est en JSON par défaut. Passez-la à jq pour conditionner des étapes suivantes ou définir des outputs de job. Ne faites pas de scraping de l'interface ; sur unsupported_operation, faites échouer l'étape et signalez-le.

Prêt à passer à la pratique ?

Démarrez votre essai FirstSales et lancez une boîte mail préchauffée et authentifiée en quelques minutes.

Commencer pour 1 $
Tous les tutoriels