Skip to main content
A pipeline calls CloudThinker with a service account credential stored as a CI secret. The job needs no browser login and keeps working when people change role or leave.

Prerequisites

  • A workspace Admin, to create the service account.
  • A CI system that stores secrets, such as GitHub Actions or GitLab CI.

Set up the token

1

Create a service account

Open Workspace settings → Service accounts, add an account such as ci-release-gate, and give it the lowest role the job needs: Developer for a job that asks CloudThinker a question, Viewer for a release gate that only reads release risk. See Service accounts.
2

Create a credential

Click Manage → Create credential. Pick only the scopes the job calls: chat:runs:write to ask a question, review:releases:read for the release gate. Set an expiry and copy the ct_sat_ value.
3

Store it as a CI secret

Save it as a masked secret named CLOUDTHINKER_TOKEN. In GitHub, use Settings → Secrets and variables → Actions. In GitLab, use Settings → CI/CD → Variables → Add variable, set Visibility to Masked, and select Protect variable so only protected branches and tags get it.

Run it in the pipeline

The examples ask CloudThinker for a release risk summary and fail the job unless the run succeeds within 15 minutes. A successful run means CloudThinker answered, not that the release is safe; to gate on release risk, see Call the API directly. Exit code 4 means the wait ran out and the run continues; exit code 5 means it paused for an approval. See Approvals for API runs.
.github/workflows/cloudthinker.yml
The installer puts the CLI in ~/.local/bin and adds it to PATH only in your shell profile, which a CI step doesn’t read. The extra line puts it on PATH for the steps that follow. To pin a CLI version instead of taking the latest, see Use it in CI. set -o pipefail keeps the CLI’s exit code when its output goes through jq. Without it, the step takes jq’s exit code and passes even when the run failed or paused. A service account credential covers its own workspace, so the job needs no workspace setting. Don’t set --workspace or CLOUDTHINKER_WORKSPACE beside CLOUDTHINKER_TOKEN: the command exits with code 2. An API token is meant for cloudthinker chat and cloudthinker api; most other CLI commands need a CLI login.

Call the API directly

For a read that needs no agent, skip the prompt and call the API. This step passes when the repository’s newest release is clear to ship, was shipped anyway by a person, or doesn’t exist yet. It fails while the release is being analyzed, is blocked, or its analysis failed. Set --project to the repository path, such as $GITHUB_REPOSITORY or $CI_PROJECT_PATH:
Any HTTP client works too. Send the token as a bearer and put the workspace ID, from workspace_ids in GET /v1/token, in the path:

Keep pipelines safe

  • One service account per pipeline, with the lowest role that pipeline needs.
  • Expose the secret only to protected branches and trusted workflows, never to jobs that run code from forks.
  • A re-run cloudthinker chat step starts a second run. To make a re-run safe, start the run with cloudthinker api chat.runs.create --set prompt="…" --key <key> and a key built from the pipeline ID, then wait with cloudthinker chat status <run-id> --wait. See Write data.
  • Rotate the credential before it expires. See Rotate and revoke.
  • Every credential of a service account, and every service account in the workspace, draws on shared hourly quotas, so a second credential adds no capacity. cloudthinker api doesn’t retry a 429; wait for Retry-After before you run the step again.

Approvals for API Runs

Decide what a pipeline run may change without a person.

Headless Chat

Exit codes and JSON output for chat runs.