# Pact Broker: sharing consumer contracts and verification results > Pact Broker is an MIT licensed Ruby application for publishing consumer driven contracts and the verification results that go with them, so that a consumer build can ask whether a provider is safe to deploy against. The judgement is that the interesting part is not the storage but the question the can-i-deploy command answers, and that the project is careful to keep the broker itself independent of the Pact framework. **pact-foundation/pact_broker** — Enables your consumer driven contracts workflow - Repository: https://github.com/pact-foundation/pact_broker - Website: http://pactflow.io - Stars: 746 · Forks: 193 - Language: Ruby - License: MIT - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/pact-foundation-pact-broker ## A place to publish contracts and read back verification results The Pact Broker is an application for sharing consumer driven contracts and verification results. The readme is precise about its scope: it is optimised for use with pacts, the contracts created by the Pact framework, but it can be used for any type of contract that can be serialized to JSON. That second clause is the important one for an architect. The broker does not understand the Pact format, it understands JSON documents that describe expectations between two named applications, and it stores, versions, links and publishes them. A team that has contracts in another format can use the same broker, as long as the format is JSON. The interface is a RESTful API for publishing and retrieving pacts, with an embedded API browser for navigating it, and the readme asks you to start with the overview page on the wiki so that you understand the HTTP resources and how they relate to each other. There is also autogenerated documentation for each pact, which is served as HTML when you paste a pact URL into a browser. There is a hosted option, PactFlow, which is a fork of the open source broker built by a group of core Pact maintainers, with an improved interface, field level verification results and federated login, and the readme says you can try a broker for free there. The distinction matters later, because those extras are not in the open source project. ## The problem is that integration test knowledge scatters across builds The readme explains why the broker exists, and the explanation is about information rather than about testing. Contract testing is an alternative to traditional integration testing that gives you tests that run faster and that stay maintainable at scale. The cost of that approach is described plainly: the information that would have been available in one place at the end of an integration test suite run, namely the version numbers of all the applications that were tested together and whether those tests passed, is now spread out across many different builds. That is the gap the broker fills. It brings the information back together and lets you deploy with safety. The benefits list spells out what you get back. You can release customer value by deploying your services independently and avoid the bottleneck of integration tests. You can solve the problem of sharing contracts and verification results between consumer and provider projects. You can tell which versions of your applications can be deployed safely together. The broker versions your contracts automatically, so the history of what a consumer expected is kept even as the consumer's own version numbers move on. It lets you ensure backwards compatibility between multiple consumer and provider versions, which the readme calls out for mobile and multi-tenant environments where several versions of a client are in the wild at once. It also provides API documentation of your applications that is guaranteed to be up to date, shows real examples of how your services interact, and visualises the relationships between your services. ## The consumer build publishes a pact with a single PUT The workflow is described in three steps, and the first one is simpler than most people expect. In the consumer CI build, the consumer project runs its tests using the Pact library to provide a mock service. While the tests run, the mock service writes the requests and the expected responses to a JSON pact file, which is the consumer contract. That file is then published to the broker. The readme notes that most Pact libraries make a task available to do this easily, and that at its simplest it is a PUT to a resource that specifies the consumer name and application version and the provider name: ``` http://my-pact-broker/pacts/provider/Animal%20Service/consumer/Zoo%20App/version/1.0.0 ``` Two details in that sentence matter. The URL carries the consumer application version, not the pact version, because the broker takes care of versioning the pact behind the scenes when its content changes. And the consumer application version is expected to increment with every CI build, so that the broker ends up with a record of which build produced which expectation. The last step of the consumer build is the webhook. When a pact is published, a webhook in the broker kicks off a build of the provider project if the pact content has changed since the previous version, which is how the provider learns that there is something new to verify without anyone watching for it. ## The provider replays the pact and publishes the result back The provider build is where the contract is checked, and the readme is clear about the sequence. The provider has a verification task configured with the URL to retrieve the latest pact between itself and the consumer, for example: ``` http://my-pact-broker/pacts/provider/Animal%20Service/consumer/Zoo%20App/latest ``` The build runs the verification task, which retrieves the pact from the broker, replays each request against the provider, and checks that the responses match the expected responses. If verification fails, the build fails. The readme then adds a joke that is doing real work, because it names the mechanism. The Pact Broker CI Nerf Gun magically determines who caused the verification to fail and shoots them, and the link points at a page about using Pact when the consumer and the provider are written by different teams. The point underneath the joke is attribution: the broker holds the pact and the provider's response, so it can say which side moved, which is the question every cross team integration dispute starts with. Finally, the results of the verification are published back to the broker by the verification tool, so the consumer team will know whether the code they have written will work in real life. That write-back is what makes the deployment question answerable later. ## can-i-deploy is the question the broker actually answers The third step returns to the consumer build, and it is the one that changes what a pipeline does. The consumer CI determines whether the pact has been verified by running the can-i-deploy command from the Pact Broker client: ``` pact-broker can-i-deploy --pacticipant CONSUMER_NAME --version CONSUMER_VERSION ... ``` If the pact has been verified, the deployment can proceed. The command is the exit point of the whole arrangement, and it is the thing you would wire into a deployment gate. Around it, the broker offers the supporting features. A matrix of compatible consumer and provider versions, so you know which versions can be safely deployed together. Badges to display pact verification statuses in your READMEs. Tags on an application version, for example prod or a feature branch name, to allow repository-like workflows. Webhooks to trigger actions when pacts change, such as running a provider build or notifying a Slack channel. Diffs between pact versions, so you can see what expectations changed. Dynamically generated network diagrams to visualise the microservice network, and the embedded API browser for exploring the API. The CLI itself is shipped as part of the project, for incorporating the Pact workflow into your continuous integration process, and the broker is also distributed as a Docker image. ## A Rack application with Postgres or SQLite behind it The repository is a Ruby application, and the layout is that of a mature Rails era service rather than a small gem. There is a config.ru, so the application is served by Rack, a Rakefile, a lib directory for the code, a db directory for the schema and migrations, a spec directory for the RSpec suite, a regression directory, a public directory for the static assets and the interface, a tasks directory, a script directory, a vendor directory, and a scaffolding directory. The gemspec is pact_broker.gemspec, and there is an OpenAPI description in pact_broker_oas.yaml alongside a pact_broker_client-pact_broker.json, which is how the client library and the server agree on the contract between them. The Docker image is the clearest description of the runtime. It is based on ruby 3.2.8 on Alpine 3.20, pinned to a specific digest, and it installs the PostgreSQL 15 client and development files alongside the SQLite development files, which tells you that both databases are supported. Bundler is pinned to the 2.0 series, the bundle is installed with the pg group, and the container runs rackup on port 9292 listening on all interfaces. There is a separate test script that runs the Rake tasks, and a database preparation script that runs rake db:prepare:test, which is how a container gets a usable database before the test suite runs. The dockerize tool is fetched in the image, which is the standard way to have a container wait for its database before it starts. The compose files cover the development, test and continuous integration cases, including two issue reproduction variants, which tells you how much of the maintainers' time goes into reproducing reported problems. ## Conclusion Pact Broker fits a team that has adopted contract testing and has reached the point where the contracts and the verification results need somewhere to live, because the broker stores both, versions them, triggers the provider build and answers the deploy question with can-i-deploy. It is the wrong choice if you have one service, because the whole value is in the coordination between teams that deploy independently, and it is the wrong choice if you need the hosted features, since field level verification results, the improved interface and federated login are PactFlow additions on top of the open source broker rather than part of it. Before you adopt it, decide between running the broker yourself and the hosted PactFlow service, and plan for the fact that the Ruby application ships as a Rack application with a Postgres or SQLite database behind it, not as a library you call from your build. ## FAQ ### What is the Pact Broker? It is an application for sharing consumer driven contracts and verification results, optimised for pacts created by the Pact framework but usable for any contract that can be serialized to JSON. It exposes a RESTful API for publishing and retrieving pacts, with an embedded API browser and autogenerated documentation for each pact. ### How does a consumer publish a pact to the broker? By making a PUT to a resource that names the consumer application version and the provider, for example http://my-pact-broker/pacts/provider/Animal%20Service/consumer/Zoo%20App/version/1.0.0. The consumer version goes in the URL, and the broker versions the pact itself when its content changes. ### What does can-i-deploy do? It is the command the consumer CI runs to find out whether the pact has been verified, using pact-broker can-i-deploy with the participant name and version. The broker also provides a matrix of compatible consumer and provider versions and badges that show verification status in a README. ### Is Pact Broker the same as PactFlow? No. PactFlow is a fork of the open source broker built by core Pact maintainers, and the readme says it adds an improved interface, field level verification results and federated login. The open source project is the MIT licensed application itself. ## Sources - [License: MIT](https://github.com/pact-foundation/pact_broker/blob/master/LICENSE) - [pact-foundation/pact_broker on GitHub](https://github.com/pact-foundation/pact_broker) - [Project website](http://pactflow.io) - [README](https://github.com/pact-foundation/pact_broker/blob/master/README.md) - [Releases](https://github.com/pact-foundation/pact_broker/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pact-foundation-pact-broker