NuevoVer cómo
FirstSales
Inicio/Tutoriales/Usar FirstSales en CI/CD y scripts
Desarrollador y CLI

Usar FirstSales en CI/CD y scripts

Ejecuta la CLI de FirstSales en pipelines — secretos enmascarados, autenticación fail-fast, dry-run en PRs y apply en main, pasos idempotentes, y acciones destructivas protegidas.

8 min de lectura·Avanzado·7 pasos
  1. 1

    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.

  2. 2

    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 nunca echo de 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 --json
  3. 3

    Falla rápido ante una clave incorrecta

    Empieza cada trabajo con whoami para 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;
}
  4. 4

    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}"
  5. 5

    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-key de 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}"
  6. 6

    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 --confirm fuera de cualquier paso que no deba eliminar, y analiza la salida --json para verificar el resultado:

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

    Analiza JSON, no hagas scraping

    Toda la salida es JSON por defecto — pásala por jq para 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 devuelve unsupported_operation, haz que el paso falle y repórtalo en lugar de buscar una alternativa.

Consejos de experto

Atajos aprendidos a fuerza de experiencia para mantener el precalentamiento en curso.

1

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.

2

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.

3

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.

4

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.

¿Listo para ponerlo en práctica?

Comienza tu prueba de FirstSales y lanza un buzón precalentado y autenticado en minutos.

Empieza por $1
Todos los tutoriales