Skip to main content

New "contract requiring verification published" webhook event released

tl;dr

The contract_requiring_verification_published webhook event is a new and improved version of the contract_content_changed event to use when triggering provider verification builds.

Webhooks in the Pact Broker can be triggered when certain predefined events occur. They are primarily used to obtain provider verification results for a pact when a new version is published with changed expectations. Historically, a webhook using the contract_content_changed event was used to trigger a build of the provider that verified just the changed pact, the URL of which would be passed through to the build using webhook template parameters.

A new and improved webhook event, contract_requiring_verification_published is now supported. It will be triggered if a pact is published with content that does not have a verification result from the main branch of the provider, or any of the deployed or released versions of the provider. The provider versions will be de-duplicated, and the webhook will then trigger once for each provider version. The provider version that needs to run the verification will be available in the webhook parameters as ${pactbroker.providerVersionNumber}. The triggered provider build must then check out the specified version of the provider codebase, and verify the changed pact, which will also be passed through via the ${pactbroker.pactUrl} parameter.

The contract_requiring_verification_published webhook has a number of advantages over the existing contract_content_changed webhook.

  • It makes it easy to obtain verification results from the test and production versions of your provider, allowing consumer versions with changed contracts that are already supported by the production provider to be deployed straight away.
  • It only triggers if there is a verification result missing for one of the critical provider versions, reducing the number of unnessary builds triggered.

Read more about the new event in the docs here to start using it.

Why we're getting rid of Pact Broker tags

tl;dr

Tags that represent branches and environments are being replaced with first class support for branches, environments, deployments and releases.

"Tags" in the Pact Broker are simple string values that belong to application version resources (aka. "pacticipant versions") that are generally used to track the git branches and environments associated with an application version. They allow us to identify specific versions when testing backwards compatability and introducing new features, and when determining if an application is safe to deploy. Tags have the advantage of being flexible and generic enough to support any development workflow.

Tags have their disadvantages though. They are similar enough to Docker tags that users expect them to work the same way, but different enough that pages of documentation need to be written to explain how to use them. The main problem with tags though, is that no semantic information that can be inferred from them - that is, it's impossible for the Broker to know whether a tag represents a git branch, an environment, or something else entirely.

Retries for can-i-deploy

The can-i-deploy tool is a CLI that ensures you are safe to deploy a consumer or provider into a given environment. To do this, it queries the Pact Broker to ensure that there is a successful verification result between the existing application versions and the application version you're about to deploy.

If you deploy to a test environment as part of your build pipeline, you may find yourself in the situation where the verification result is unknown because the provider build is still running. What typically would happen is that a changed pact would trigger a provider build via a webhook in the Pact Broker, and the provider may not have finished before can-i-deploy is invoked.

To help out in this scenario, you can now use the following two options to let the can-i-deploy command poll until all the verification results arrive.

[--retry-while-unknown=TIMES]
# The number of times to retry while there is an unknown
# verification result
# (ie. the provider verification is likely still running)
# Default: 0
[--retry-interval=SECONDS]
# The time between retries in seconds.
# Use in conjuction with --retry-while-unknown
# Default: 10

Remember, however, that changes to pacts are best introduced on feature branches of your consumer. This allows your pact to be "pre-verified" by the time the branch is merged into master, which will mean can-i-deploy should never block your master build.

You can read about how to do this in The steps to reaching Pact Nirvana.

Want to use this new feature? You'll need version 1.48.0 or later of the Pact CLI, and version 2.23.4 or later of the Pact Broker

Welcome!

Pact is a tool for implementing "consumer driven contracts" - a technique for testing integrations without using traditional integration tests. It was first written at realestate.com.au to help a team of developers escape the integration test hell of a rapidly expanding HTTP microservices network, and has since grown to become an open source project for contract testing in multiple languages and protocols.

Since its creation in 2013, Pact has come a long way. We're always adding new features in response to the feedback we get from our users and our own experience, but recently we've realised that we've done a poor job of letting everyone know about the awesome new things we've added along the way.

So, we've started blog.pact.io as a place to let everyone know about new features in Pact, to share people's Pact experiences (good and bad!), and to help build a community of Pact users who can help each other. If you haven't already, please join us at slack.pact.io, and if you'd like to contribute a post to our blog, chat to us on the #blog channel.