Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
This branch is 1 commit ahead, 2899 commits behind pact-foundation:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Pact Broker

Build Status Join the chat at

The Pact Broker provides a repository for consumer driven contracts created using the pact gem.


  • solves the problem of how to share pacts between consumer and provider projects
  • allows you to decouple your service release cycles
  • provides API documentation that is guaranteed to be up-to date
  • shows you real examples of how your services interact
  • allows you to visualise the relationships between your services


  • A RESTful API for publishing and retrieving pacts.
  • An embedded HAL browser for navigating the API.
  • Autogenerated documentation for each pact.
  • Dynamically generated network diagrams.
  • Enables a pact version to be tagged (ie. "prod") so a provider can verify itself against a fixed version of a pact to ensure backwards compatibility.
  • Webhooks to trigger a provider build when a consumer publishes a change to a pact.
  • Tracks changes between Pact versions so you can tell when a consumer has changed its expectations.
  • Docker Pact Broker

Travis CI Status: Build Status

How would I use the Pact Broker?

Step 1. Consumer CI build

  1. The consumer project runs its tests using the Pact library to provide a mock service.
  2. While the tests run, the mock service writes the requests and the expected responses to a JSON "pact" file - this is the consumer contract.
  3. The generated pact is then published to the Pact Broker. This is simply a PUT to a resource that specifies the consumer name and version, and the provider name. eg http://my-pact-broker/pacts/provider/Animal%20Service/consumer/Zoo%20App/version/1.0.0

Step 2. Provider CI build

  1. The provider has a verification task that is configured with the URL to retrieve the dynamically calculated latest pact between itself and the consumer. eg http://my-pact-broker/pacts/provider/Animal%20Service/consumer/Zoo%20App/latest. The "latest" version is determined by the Pact Broker by inspecting the consumer version number specified when each pact was published.
  2. The provider build runs the pact verification task, which retrieves the pact from the Pact Broker, replays each request against the provider, and checks that the responses match the expected responses.
  3. If the pact verification fails, the build fails. The Pact Broker CI Nerf Gun magically determines who caused the verification to fail, and shoots them.

If you don't have a Pact Broker CI Nerf Gun, you'll probably want to read about using pact when the consumer and provider are being written by different teams.


See the Pact Broker Client for documentation on how to publish a pact to the Pact Broker, and configure the URLs in the provider project.

See the wiki for documentation related to the Pact Broker itself.



Autogenerated documentation

Paste the pact URL into a browser to view a HTML version of the pact.

Network diagram

HAL browser

Use the embedded HAL browser to navigate the API.

HAL documentation

Use the HAL browser to view documentation as you browse.


To have a play around on your local machine

  • Install ruby 2.2.0 or later and bundler >= 1.12.0
  • Run git clone && cd pact_broker/example
  • Run bundle
  • Run bundle exec rackup -p 8080
  • Open http://localhost:8080 and you should see a list containing the pact between the Zoo App and the Animal Service.
  • Click on the arrow to see the generated HTML documentation.
  • Click on either service to see an autogenerated network diagram.
  • Click on the HAL Browser link to have a poke around the API.
  • Click on the book icon under "docs" to view documentation related to a given relation.


In a hurry? Hate having to run your own infrastructure? Check out the Hosted Pact Broker - it's fast, it's secure and it's free!

For reals

You can use the Pact Broker Docker container or Terraform on AWS or to roll your own...

  • Create a database using a product that is supported by the Sequel gem (listed on this page The migrations have been tested on MySQL and PostgreSQL - your mileage will vary on other databases.
  • Note: It is recommended to use PostgreSQL as it will support JSON search features that are planned in a future release, however MySQL the other semi supported database.
  • Install ruby 2.2.0 or later and bundler >= 1.12.0
  • Copy the example directory to the location you want to install the application.
  • Modify the and Gemfile as desired (eg. choose database driver gem, set your database credentials. Use the "pg" gem if using Postgres.)
  • Please ensure you use encoding: 'utf8' in your Sequel options to avoid encoding issues.
  • For production usage, use a web application server like Phusion Passenger or Nginx to serve the Pact Broker application.
  • Deploy to your location of choice.


The Pact Broker enables you to share your pacts between projects, and make them useful for people too.







No packages published


  • Ruby 48.5%
  • JavaScript 48.1%
  • HTML 2.2%
  • CSS 1.1%
  • Shell 0.1%