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.
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'echode 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Échouez rapidement en cas de mauvaise clé
Démarrez chaque job avec
whoamiafin 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; }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}"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}"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--confirmhors de toute étape qui ne devrait pas supprimer, et parsez la sortie--jsonpour vérifier le résultat :firstsales connectors delete --org "$ORG" --workspace "$WS" \ --connector "$STALE_ID" --confirm --json | jq -e '.deleted == true'Parsez le JSON, ne faites pas de scraping
Toute la sortie est en JSON par défaut : passez-la à
jqpour 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 renvoieunsupported_operation, faites échouer l'étape et remontez l'erreur plutôt que de la contourner.
Astuces de pro
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.
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.
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.
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.