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 Actions
- GitLab CI
.github/workflows/cloudthinker.yml
~/.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:
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 chatstep starts a second run. To make a re-run safe, start the run withcloudthinker api chat.runs.create --set prompt="…" --key <key>and a key built from the pipeline ID, then wait withcloudthinker 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 apidoesn’t retry a429; wait forRetry-Afterbefore you run the step again.
Related
Approvals for API Runs
Decide what a pipeline run may change without a person.
Headless Chat
Exit codes and JSON output for chat runs.