Run and observe
CI and the API
Gate deployments in CI with the safety check and record what you deploy, using an API token and the HTTP API.
Open API & CI in the appWhat you can do from CI today
Rabbinatix has an HTTP API for CI pipelines. With an API token you can:
- check whether a release can go to an environment (the safety check,
can-i-deploy); - record a deployment after it succeeds;
- list your systems and read the status of their contracts.
You call it with any HTTP client, such as curl, from any CI system. Integrations → API & CI shows the same examples with your own address and a system of yours filled in, ready to copy, and a GitHub Actions workflow built from them.
Create an API token
- Open Integrations and go to API tokens.
- Click New token.
- Give it a Name, such as
GitHub Actions. - Pick its Scopes. Pick only what the pipeline needs.
- Click Create token and copy the token. It starts with
cm_live_and is shown only once.
Store the token as a secret in your CI system, for example RABBINATIX_TOKEN. The list shows each token's scopes and Last used. Revoke stops a token at once: pipelines using it fail on their next call.
AI assistants use keys of their own, not API tokens. See API and tokens.
The API address
Copy the Base URL from Integrations → API & CI. It ends in /v1. Set it once in your pipeline:
export RABBINATIX_API="https://<your functions host>/api/v1" # the Base URL
export RABBINATIX_TOKEN="cm_live_…" # from your CI secretsEvery request sends the token as a bearer token. Check it works:
curl -s "$RABBINATIX_API/whoami" -H "Authorization: Bearer $RABBINATIX_TOKEN"The routes
System IDs come from GET /v1/systems. Environment IDs are dev, staging and prod unless you added your own.
You rarely call these yourself: the rabbinatix CLI wraps each one with readable output and exit codes. Every command: The rabbinatix CLI.
Gate a deployment
The safety check runs the same check as the Safety check view on the Deployments page. It answers with approved (true or false), the contracts that block, and output: the same lines the app prints. Leave out version to check the system's current declarations.
The call succeeds even when the deployment is blocked, so your script decides to stop:
result=$(curl -sf "$RABBINATIX_API/can-i-deploy?system=auth-service&version=2.5.0&env=prod" \
-H "Authorization: Bearer $RABBINATIX_TOKEN")
echo "$result" | jq -r .output
echo "$result" | jq -e .approved > /dev/null || exit 1A blocked check is also an event: it shows in the activity log and can notify people through deployment.blocked webhooks.
Record a deployment
After the deploy succeeds, tell Rabbinatix what now runs where:
curl -sf -X POST "$RABBINATIX_API/deployments" \
-H "Authorization: Bearer $RABBINATIX_TOKEN" \
-H "content-type: application/json" \
-d '{"system":"auth-service","version":"2.5.0","env":"staging"}'The release must exist already: make it under Releases in the sidebar first. Development always runs what is published, so recording there answers 409. An environment that asks for approval first answers 202 with a move request for its suggested approvers; send "approval":"none" to record it at once instead (the answer says "withoutApproval": true, and so does the deployment). With no approvers set there, it is recorded at once, without approval. The CLI's rabbinatix deploy record --no-approval does the same. The deployment shows on Deployments with API · <token name> as who recorded it.
A full pipeline step
- Build and test as usual.
- Run the safety check for the target environment. Stop when
approvedis false. - Deploy.
- Record the deployment.
Run steps 2 to 4 for each environment you move releases to, such as staging and then production.
Check what a pull request affects
rabbinatix impact runs in your pull request pipeline and says what the change affects on the map: the logic its code belongs to, the flows and contracts around it, and the test cases worth running. It reads the code on the CI machine and sends only keys, names, file paths and line numbers. Integrations → API & CI has a GitHub Actions workflow to copy:
npx -y rabbinatix impact --store --comment impact.md # needs RABBINATIX_API and RABBINATIX_TOKEN
gh pr comment "$PR" --edit-last --body-file impact.md # one comment, updated on each push--store needs a token with the deploy scope; reading the answer needs only read. How to set it up, every option, and how to read the reports on the Code impact page: Code impact.
Errors
Related
- Environments and deploymentsRecord which release of each system runs in each environment, see compatibility per environment, and check a release before you deploy it.
- API and tokensCreate API tokens for CI and scripts, choose their scopes, and call the REST API at /api/v1.
- IntegrationsSend contract and ticket events to your own endpoint or an email address with webhooks, and see each delivery and its retries.
- Versions and releasesRun API versions side by side, read the history and diff of every endpoint, create releases with a suggested version, and check old copies.
