Run and observe
Environments and deployments
Record which release of each system runs in each environment, see compatibility per environment, and check a release before you deploy it.
Open Deployments in the appWhy environments matter
A contract can be fine on paper and broken in production. If Web App 3.1 is in production but Auth Service there is still 2.4, what matters is whether those two versions agree. Rabbinatix answers that per environment: it checks contracts using the releases that are deployed in each one.
Your environments
Each organization or project starts with three environments: Development, Staging and Production (IDs dev, staging and prod).
To change them, open Environments in the sidebar (the Delivery group).
- To rename one, edit its name in the list.
- To add one, type a name such as
QAand click Add. - To remove one, click the trash button next to it. You can't remove the last environment.
Each row shows how many deployments the environment has. You need permission to manage releases to change environments.
Releases come first
A deployment records a release of a system in an environment. A release saves the system's endpoints as they are at a version, such as 2.4.0. To make one, open Releases in the sidebar, pick the system and click New release. See Versions and releases.
Move releases to the next environment
Development runs what you publish. To get it into Production (or Staging, QA and so on), check it, then publish it:
- Open Deployments and press Move to next environment at the top. To check one release first, open the Safety check view, pick the System, its Version and the Environment, and press Run the safety check (the arrow next to a system under Where it runs opens it with these filled in and runs the check for you); when it passes, Move to next environment also shows under it, for what you checked.
- When the check finds problems, Move anyway shows under Run the safety check instead, in red. It asks you first, needs the Manage environments permission, and the move request and the activity log say it was forced past the safety check.
- The dialog lists every release that would move. The releases you tick are checked together, each as if the others were already there, so a system and the provider it calls can move in the same batch. For Production, one the safety check blocks says "Blocked by the safety check" beside it, with why: Production takes nothing the check blocks.
- If the environment asks for approval first (Production does at first), choose under Approval. Approvals never block: they are how someone else shares the call, and going ahead without one is recorded.
The approvers list suggests your manager and your team's lead (from the org chart); an approver who is away says who stands in for them, with a button to add them. A review that waits more than two working days says whom to ask instead (the approver's manager).
- Needs approval: pick the Approvers. Only people whose role may move releases are offered, and only they can approve. They review the move; once approved, someone who may move releases presses Move to the environment on the request (they are told it waits for them).
- No approval needed: Continue moves the releases at once (the safety check still runs). Anyone who may move releases may choose it; the move request, the deployment and the activity log say Without approval, by whom.
- With approval, press Move to the environment on the request once it is approved. An environment that asks for no approval also moves at once on Continue.
Publishing your changes to Development works the same way when Development asks for approval: Submit for review offers No approval needed to whoever may publish changes (recorded as without approval), and only people whose role may publish changes are offered as approvers (a viewer is not). Each change in the review reads in words first; Show the exact change shows the rest, a logic as its text steps, before and after.
Record a deployment
Recording a deployment tells Rabbinatix that a release is now running in an environment, because it was deployed there outside Rabbinatix: by your CI, or by hand. Development always runs what is published, so it isn't offered. An environment that asks for approval first (Production at first) is offered too: the dialog says so, and the deployment is recorded as Without approval, by you. To have someone approve it, use Move to next environment instead.
In CI you usually record deployments through the API (see CI and the API). You can also record one by hand:
- Open Deployments from the sidebar.
- Click Add a deployment by hand.
- Pick the System, the Release and the Environment.
- Click Add.
If the system has no releases yet, the dialog tells you to create one first. You can also click the pencil next to any cell under Where it runs to add a deployment for that system and environment. Add a deployment by hand and the pencils only show for people with the Releases & deployments permission.
The Deployments page
Pick a view at the top. It opens on Waiting when a move request or a sign-off waits for you (the sidebar's number), otherwise on Where it runs.
Click a release under Where it runs to open it on the Releases page. Click a connection's cell to see it on the system map in that environment.
Undo removes a deployment that was recorded by mistake. The row reads Undoing… while it goes, then leaves the list; the environment then shows what was deployed before. Undoing needs only the Releases & deployments permission, also where moving asks for approval first. Under Move requests, a move whose releases no longer run there (undone, or replaced since) reads Moved · no longer runs there.
Safety check
Before you move a release, check whether it would break anything in the target environment.
- On Deployments, open the Safety check view.
- Pick the System, a Version (or Latest, not released yet for the current declarations) and the Environment.
- Click Run the safety check.
Rabbinatix takes the releases deployed in that environment, puts your candidate in place of the system's current one, and evaluates every contract where the system is a consumer or a provider. The output lists each connected system:
Checking Production compatibility for Auth Service 2.5.0…
✓ Mobile App consumer 3/3 compatible
✗ Web App consumer 1/2 compatible
GET /api/v2/me id is expected as integer but the other side uses string.
Deployment blocked: Web App's calls would break. 1 of 2 connected systems compatible.The last line says why: whose calls would break, or which API the system calls that isn't provided yet.
A release is blocked when:
- any of its contracts would be broken in that environment. That includes a Design conflict: an endpoint still marked To do or In progress that doesn't give what a caller in that environment expects. Its Lifecycle doesn't make it safe, because the caller runs there; the line under it says "The endpoint is marked To do (or In progress), but … calls it in …";
- the target is production and the system calls an API that doesn't exist there yet (unresolved);
- a critical flow through the system has a failing latest test case run.
In Development, calls that would break don't block: Development is where work in progress runs. The connected system shows with ! instead of ✗, and the last line says it is safe, with a warning:
Safe to deploy to Development, with a warning: Web App's calls would break. 1 of 2 connected systems compatible. Other environments block this until it is fixed.Every other environment blocks the same release. A failing critical flow blocks in Development too.
A blocked check lists Critical flows that would fail with links to the failing runs, Open tickets on the contracts that block this, and Discuss this release to start a chat thread about it. You can run the same safety check in chat with the /safety-check command.
The map in an environment
The system map has an Environment tab on its left, one choice per environment. Development is the default and where you work: contracts as they are declared now, your own unpublished changes included, and the map can be edited. Any other environment is read-only and shows only the systems running there, with the releases moved there; until something is moved there, it is empty. The app remembers the environment you chose for each project in this browser. A connection can be compatible in staging and broken in production.
Logic and flows in an environment
A release holds its system's logic and the flows that start in it, each at the revision it had then. With another environment picked in the header, Logic and Flows list what the releases running there hold, read-only: each logic and flow at the revision deployed there (for example "rev 4 · in 1.2.0"), with Development's newer revision named when it has moved on. Opening one shows that revision; the note under its toolbar names it ("Viewing Production: rev 4 from Orders API 1.2.0, read-only."). A flow's page there has no Test button: runs use Development's logic.
- Something deleted in Development but still deployed stays listed there, marked "Deleted in Development", and still opens.
- A release made before releases recorded their logic and flows says so ("doesn't list its logic: it was released before releases recorded it"). Its next release will.
- Reusable logic isn't released on its own: it runs inside the logic that calls it.
- With nothing deployed there yet, the lists say "Nothing deployed here yet".
Related
- 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.
- CI and the APIGate deployments in CI with the safety check and record what you deploy, using an API token and the HTTP API.
- Contract statusesWhat each status means, how one contract colours a connection and a system, how to read a contract, and how to tune the checks.
- The system mapYour systems and the connections between them on one canvas, coloured by contract health, with a table and a Connections view.
- Change impact and Draft modeSee what an API change would break before anyone feels it, share the drafts for review, and publish them when they are right.
