can-i-deploy and contract versioning: the deployment-safety gate

Priya’s checkout-web adds a feature that needs a new field, discount_cents. She updates the consumer test, the pact regenerates, and CI publishes it to the broker. Sam’s pricing provider hasn’t shipped discount_cents yet — the verification job against pricing’s latest build is green for the old interactions and the new one is still flagged pending, so nobody’s build is red. Priya’s pipeline is all green, so it deploys checkout-web to prod. Forty seconds later the error rate climbs: the pricing instance actually running in prod is three versions behind pricing’s latest, and it returns no discount_cents. The pact was verified — just not against the version that was there. Contract testing did its job and the deploy still broke prod, because the gate was asking the wrong question.

A green pact is a pairwise fact, not a deploy-safety fact

Lesson 03 left you with a broker full of verification results. Each result is a precise, narrow statement: consumer version X’s pact was verified against provider version Y, and it passed. That is genuinely useful, but it answers a question nobody is actually asking at deploy time. The deploy-time question is: if I push consumer version X to production right now, will it work against the provider version that is physically running in production? The verification you have is for some version Y — typically the provider’s latest CI build — which may be several deploys ahead of what’s in prod.

This is the gap the Hook falls through. The pact was verified against pricing’s newest build, which already had discount_cents. But prod was running an older pricing, and the broker’s individual verification results never said a word about which provider version was deployed where. A pile of green checkmarks tells you which pairs of versions have been tested together; it does not tell you whether the specific pair you’re about to create in production — new consumer, old provider — is one of the green ones. You need a tool that crosses your version against the target environment’s actual occupants, and that tool is can-i-deploy.

The matrix: every tested pair, and what’s deployed where

The broker assembles all of this into the matrix — a table of every consumer version × provider version that has ever been tested against each other, with the pass/fail of each pairing. Two things feed it. First, verification results: when a pact for consumer version X is verified by provider version Y, the broker records the cell (X, Y) → pass/fail. Second, deployment records: when you actually deploy a version into an environment, you tell the broker, so it knows that prod currently holds, say, pricing v56. can-i-deploy then does one query: take the version I want to deploy, find the versions of every integrated app currently in the target environment, and check that every required cell between them is green.

The last two rows are the whole lesson. checkout-web v24 is verified — against pricing v59, the build that already has discount_cents. But v59 isn’t deployed; prod still runs v56. can-i-deploy --pacticipant checkout-web --version 7c8d9e0 --to-environment production ignores the v59 result entirely, finds no green cell for (v24, v56), exits non-zero, and stops the pipeline. The exact deploy that paged Priya in the Hook is the deploy this gate refuses.

Versions must be the git SHA, and deployments must be recorded

The matrix only works if two pieces of bookkeeping are right. First, the version number. Pact’s strong recommendation is that a pacticipant version is the git commit SHA, or contains it (e.g. 0.0.10+76a39e5). The reason is mechanical: the version must change exactly when the pact could change. If you version by package.json semver, two different builds with different contracts can share version 2.3.0, and the broker will happily reuse a stale verification result for the wrong code. The git SHA changes on every commit, is known at deploy time, and lets you post the verification status back as a commit status. Feature branches automatically get distinct versions from main. The SHA is the only identifier that’s guaranteed to track the contract.

Second, deployment tracking. The broker can’t know what’s in prod unless you tell it, at the end of every deploy, with pact-broker record-deployment --pacticipant checkout-web --version 7c8d9e0 --environment production. There are two flavors. record-deployment is for things deployed to a known instance — services, consumers, APIs — and it automatically marks the previous version in that environment as no longer deployed, because only one version runs at a time. record-release is for artifacts you publish but don’t replace — mobile apps in a store, libraries in a registry — where many released versions coexist, so it does not undeploy the prior one. (Older setups used environment tags like prod for the same purpose; tags still work, and brokers since 2.81.0 auto-convert an environment-named tag into a deployment, but deployed/released versions are the model going forward.)

Independent deployability is the entire payoff

Step back and notice what this buys. Without the gate, “is it safe to deploy?” can only be answered by deploying everything together in lockstep, or by booting the whole world in a shared environment — the exact N² problem the first lesson killed. With the gate, each service answers the question for itself, locally, against the recorded truth of every environment: I can deploy my new version iff every app already in the target env has a green pact with me. That is independent deployability — the ability to ship one service on its own schedule without coordinating a flight of releases — and it is the whole reason the unit exists. Contract tests catch the break; can-i-deploy is what lets you act on that knowledge safely, one service at a time.

The failure mode when you skip it is precisely the Hook: a consumer whose new expectations the prod provider has never satisfied sails through CI (its pact is verified against the provider’s latest, not its deployed version) and breaks at runtime — reintroducing the exact production outage contract testing was supposed to prevent. The verification was real; the deploy decision ignored it. The gate’s job is to make the deploy decision use the matrix instead of vibes.