Prefira a CLI em pipelines
Para jobs de CI/CD e scripts locais, a documentação recomenda a CLI em vez de HTTP puro: ela centraliza o gerenciamento de credenciais, emite JSON estável que suas etapas conseguem parsear, e mantém as proteções contra operações destrutivas que você quer em automação. Uma ferramenta, um caminho de autenticação, saída consistente.
Injete a chave como um secret mascarado
Guarde sua chave de API de desenvolvedor no cofre de secrets do seu provedor de CI (GitHub Actions secrets, variáveis do GitLab CI, etc.) e exponha-a como
FIRSTSALES_API_KEY. Nunca fixe (hardcode) a chave no arquivo de workflow. A maioria dos sistemas de CI mascara valores secretos nos logs automaticamente: mantenha assim nunca dandoechona chave.# Etapa de job do GitHub Actions - name: FirstSales sync env: FIRSTSALES_API_KEY: ${{ secrets.FIRSTSALES_API_KEY }} run: | npm install -g @firstsales.io/cli firstsales whoami --jsonFalhe rápido em uma chave ruim
Comece todo job com
whoamipara que o pipeline pare imediatamente se a chave estiver errada ou revogada, em vez de rodar uma sincronização pela metade:firstsales whoami --json > /dev/null || { echo "FirstSales auth failed"; exit 1; }Planeje com --dry-run, depois aplique
Em automação você quer uma prévia antes de escrever. Coloque as mutações reais atrás de uma etapa de plano usando
--dry-run(por exemplo, em pull requests), e só aplique na branch principal:# PR / plano: apenas pré-visualização firstsales contacts create --org "$ORG" --workspace "$WS" \ --data-file ./new-lead.json --dry-run # main / aplicar: escrita real, idempotente firstsales contacts create --org "$ORG" --workspace "$WS" \ --data-file ./new-lead.json \ --idempotency-key "lead-${GITHUB_SHA}"Torne etapas retentáveis idempotentes
Etapas de CI são reexecutadas: por runners instáveis, por humanos re-rodando um job. Derive um
--idempotency-keyde algo estável (um commit SHA, um ID de linha, um número de execução) para que uma reexecução não crie tudo em dobro:firstsales contact-imports create --org "$ORG" --workspace "$WS" \ --data-file ./import.json \ --idempotency-key "import-${CI_PIPELINE_ID}"Proteja etapas destrutivas
Exclusões exigem
--confirm, que é exatamente o que você quer em um pipeline: um job de limpeza só pode remover dados quando a flag está explicitamente presente. Mantenha--confirmfora de qualquer etapa que não deveria excluir, e faça parse da saída--jsonpara validar o resultado:firstsales connectors delete --org "$ORG" --workspace "$WS" \ --connector "$STALE_ID" --confirm --json | jq -e '.deleted == true'Faça parse do JSON, não faça scraping
Toda a saída é JSON por padrão: encaminhe para
jqpara tomar decisões, definir outputs do job ou controlar etapas seguintes. Nunca raspe a interface do app ou acesse endpoints privados a partir do CI; se um comando retornarunsupported_operation, falhe a etapa e reporte o problema em vez de contorná-lo.
Dicas de especialista
whoami como a primeira etapa do job
Uma verificação de autenticação de uma linha no topo do job transforma uma chave ruim/expirada em uma falha instantânea e óbvia, em vez de uma execução parcial e confusa.
Derive chaves de idempotência de variáveis de CI
Commit SHA, ID do pipeline, número da execução: qualquer valor estável por execução torna uma etapa repetida um no-op seguro. Nunca use um timestamp ou valor aleatório; eles anulam o propósito.
Duas fases: dry-run em PRs, apply na main
Espelha infraestrutura como código. --dry-run em pull requests mostra o diff para revisão; a escrita real só roda depois do merge. Segurança barata para ações irreversíveis.
Valide a saída JSON
Encaminhe --json para jq -e para que a etapa realmente falhe quando o resultado não é o esperado, em vez de sair com código 0 num erro silencioso.
Perguntas frequentes
O CI deve usar a CLI ou a API?
A CLI. Para CI/CD e scripts, ela é recomendada em vez de HTTP puro porque padroniza o gerenciamento de credenciais e a saída, e mantém as proteções contra operações destrutivas já embutidas.
Como lido com a chave de API no CI?
Coloque-a no cofre de secrets do seu provedor de CI e exponha-a como FIRSTSALES_API_KEY. Não a fixe (hardcode) no workflow, e nunca dê echo nela: a maioria dos sistemas de CI só mascara secrets nos logs se você não os imprimir você mesmo.
Como pré-visualizo uma mudança antes de ela rodar?
Use --dry-run para imprimir a requisição sem enviá-la. Um padrão comum é dry-run em pull requests e a escrita real só na branch principal.
Como torno uma etapa segura para reexecução?
Passe --idempotency-key derivada de um valor estável, como o commit SHA ou o ID do pipeline. Uma etapa reexecutada com a mesma chave vira um no-op em vez de uma escrita duplicada.
Como evito que um job de limpeza exclua demais?
Exclusões exigem --confirm, então uma etapa só consegue remover dados quando a flag está explicitamente presente. Mantenha-a fora de etapas não destrutivas, e valide o resultado --json com jq -e.
Posso tomar decisões a partir da saída?
Sim: a saída é JSON por padrão. Encaminhe para jq para controlar etapas seguintes ou definir outputs do job. Não raspe a interface do app; em unsupported_operation, falhe a etapa e reporte.