Usando o FirstSales em CI/CD e Scripts

Execute a CLI do FirstSales em pipelines — segredos mascarados, autenticação fail-fast, dry-run em PRs e apply na main, etapas idempotentes e ações destrutivas protegidas.

8 min de leitura·Avançado·7 etapas

1
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.
2
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 dando echo na 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 --json
```
3
Falhe rápido em uma chave ruim
Comece todo job com whoami para 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}"

5
Torne etapas retentáveis idempotentes
Etapas de CI são reexecutadas — por runners instáveis, por humanos re-rodando um job. Derive um --idempotency-key de 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}"
```
6
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 --confirm fora de qualquer etapa que não deveria excluir, e faça parse da saída --json para validar o resultado:
```
firstsales connectors delete --org "$ORG" --workspace "$WS" \
  --connector "$STALE_ID" --confirm --json | jq -e '.deleted == true'
```
7
Faça parse do JSON, não faça scraping
Toda a saída é JSON por padrão — encaminhe para jq para 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 retornar unsupported_operation, falhe a etapa e reporte o problema em vez de contorná-lo.

Dicas de especialista

Atalhos conquistados na prática que mantêm o aquecimento nos trilhos.

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.

Pronto para colocar isso em prática?

Comece seu teste do FirstSales e lance uma caixa de e-mail aquecida e autenticada em minutos.

Comece por $1

Todos os tutoriais

Usando o FirstSales em CI/CD e Scripts

Prefira a CLI em pipelines

Injete a chave como um secret mascarado

Falhe rápido em uma chave ruim