Prioriza la CLI en los pipelines
Para trabajos de CI/CD y scripts locales, la documentación recomienda la CLI por encima de HTTP en crudo: centraliza el manejo de credenciales, emite JSON estable que tus pasos pueden analizar, y mantiene las salvaguardas de operaciones destructivas que quieres en la automatización. Una sola herramienta, un solo camino de autenticación, salida consistente.
Inyecta la clave como secreto enmascarado
Guarda tu Developer API key en el almacén de secretos de tu proveedor de CI (GitHub Actions secrets, GitLab CI variables, etc.) y expónla como
FIRSTSALES_API_KEY. Nunca la codifiques directamente en el archivo de workflow. La mayoría de los sistemas de CI enmascaran los valores secretos en los logs automáticamente: mantenlo así no haciendo nuncaechode la clave.# GitHub Actions job step - name: FirstSales sync env: FIRSTSALES_API_KEY: ${{ secrets.FIRSTSALES_API_KEY }} run: | npm install -g @firstsales.io/cli firstsales whoami --jsonFalla rápido ante una clave incorrecta
Empieza cada trabajo con
whoamipara que el pipeline se detenga de inmediato si la clave es incorrecta o fue revocada, en lugar de ejecutar una sincronización a medias:firstsales whoami --json > /dev/null || { echo "FirstSales auth failed"; exit 1; }Planifica con --dry-run, luego aplica
En automatización quieres una vista previa antes de escribir. Condiciona las mutaciones reales a un paso de plan usando
--dry-run(por ejemplo, en pull requests), y solo aplica en la rama principal:# 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}"Haz que los pasos reintentables sean idempotentes
Los pasos de CI se reintentan: por runners inestables, por humanos que vuelven a ejecutar un trabajo. Deriva una
--idempotency-keyde algo estable (un commit SHA, un ID de fila, un número de ejecución) para que una reejecución no cree duplicados:firstsales contact-imports create --org "$ORG" --workspace "$WS" \ --data-file ./import.json \ --idempotency-key "import-${CI_PIPELINE_ID}"Protege los pasos destructivos
Los deletes requieren
--confirm, que es exactamente lo que quieres en un pipeline: un trabajo de limpieza solo puede eliminar datos cuando la flag está explícitamente presente. Mantén--confirmfuera de cualquier paso que no deba eliminar, y analiza la salida--jsonpara verificar el resultado:firstsales connectors delete --org "$ORG" --workspace "$WS" \ --connector "$STALE_ID" --confirm --json | jq -e '.deleted == true'Analiza JSON, no hagas scraping
Toda la salida es JSON por defecto: pásala por
jqpara tomar decisiones, establecer outputs del job, o condicionar pasos posteriores. Nunca hagas scraping de la interfaz de la app ni llames a endpoints privados desde CI; si un comando devuelveunsupported_operation, haz que el paso falle y repórtalo en lugar de buscar una alternativa.
Consejos de experto
whoami como el primer paso del job
Una verificación de autenticación de una línea al principio del job convierte una clave mala o expirada en un fallo instantáneo y obvio en lugar de uno parcial y confuso.
Deriva las idempotency keys de variables de CI
Commit SHA, pipeline ID, número de ejecución: cualquier valor estable por ejecución convierte un paso reintentado en un no-op seguro. Nunca uses un timestamp o un valor aleatorio; eso anula el propósito.
Dos fases: dry-run en PRs, apply en main
Refleja infraestructura como código. --dry-run en pull requests muestra el diff para revisión; la escritura real solo se ejecuta después del merge. Seguridad barata para acciones irreversibles.
Verifica sobre la salida JSON
Pasa --json por jq -e para que el paso realmente falle cuando el resultado no es el esperado, en lugar de salir con código 0 ante un error silencioso.
Preguntas frecuentes
¿Debería CI usar la CLI o la API?
La CLI. Para CI/CD y scripts se recomienda por encima de HTTP en crudo porque estandariza el manejo de credenciales y la salida, y mantiene incorporadas las salvaguardas de operaciones destructivas.
¿Cómo manejo la clave de la API en CI?
Colócala en el almacén de secretos de tu proveedor de CI y expónla como FIRSTSALES_API_KEY. No la codifiques directamente en el workflow, y nunca hagas echo de ella: la mayoría de los sistemas de CI enmascaran los secretos en los logs solo si tú no los imprimes.
¿Cómo previsualizo un cambio antes de que se ejecute?
Usa --dry-run para imprimir la solicitud sin enviarla. Un patrón común es dry-run en pull requests y la escritura real solo en la rama principal.
¿Cómo hago que un paso sea seguro de reintentar?
Pasa --idempotency-key derivada de un valor estable como el commit SHA o el pipeline ID. Un paso reintentado con la misma clave es un no-op en lugar de una escritura duplicada.
¿Cómo evito que un job de limpieza elimine de más?
Los deletes requieren --confirm, así que un paso solo puede eliminar datos cuando la flag está explícitamente presente. Mantenla fuera de los pasos no destructivos, y verifica el resultado de --json con jq -e.
¿Puedo tomar decisiones a partir de la salida?
Sí: la salida es JSON por defecto. Pásala por jq para condicionar pasos posteriores o establecer outputs del job. No hagas scraping de la interfaz; ante unsupported_operation, haz que el paso falle y repórtalo.