NOTE: This page describes how to configure the native Ruby Pact Broker application. The Pact Broker Ruby application is distributed in 2 different Docker images, one based on Puma (this is our default recommendation) and one based on Passenger (older, but still supported). Each of the Docker images is configurable using environment variables that map to the Ruby Pact Broker application configuration options. Please see the documentation for your Docker image for the names and formats of the environment variables.
The Pact Broker configuration settings are applied in the
config.ru file. See the Pact Broker example application if you are unfamiliar with Ruby applications.
Change them to your desired values in the
If your broker needs to execute a webhook against a server that has a self signed certificate, you will need to add the certificate to the broker's certificate store. Currently, the way to do this is to use the script script/insert-self-signed-certificate-from-url.rb. The easiest way to run this is to copy it to the machine where the broker is deployed, and modify the database credentials to match those of your broker.
If your webhooks need to execute via a HTTP proxy, set the
http_proxy environment variable to the address of your proxy.
To ensure that webhooks cannot be used maliciously to expose either data about your contracts or your internal network, the following validation rules are applied to webhooks via the Pact Broker configuration settings.
Scheme: Must be included in the
webhook_scheme_whitelist, which by default only includes
https. You can change this to include
httpif absolutely necessary, however, keep in mind that the body of any http traffic is visible to the network. You can load a self signed certificate into the Pact Broker to be used for https connections using script/insert-self-signed-certificate-from-url.rb in the Pact Broker Github repository.
HTTP method: Must be included in the
webhook_http_method_whitelist, which by default only includes
POST. It is highly recommended that only
POSTrequests are allowed to ensure that webhooks cannot be used to retrieve sensitive information from hosts within the same network.
Host: If the
webhook_host_whitelistcontains any entries, the host must match one or more of the entries. By default, it is empty. For security purposes, if the host whitelist is empty, the response details will not be logged to the UI (though they can be seen in the application logs at debug level).
The host whitelist may contain hostnames (eg
"github.com"), IPs (eg
"192.0.345.4"), network ranges (eg
"10.0.0.0/8") or regular expressions (eg
/.*\.foo\.com$/). Note that IPs are not resolved, so if you specify an IP range, you need to use the IP in the webhook URL. If you wish to allow webhooks to any host (not recommended!), you can set
[/.*/]. Beware of any sensitive endpoints that may be exposed within the same network.
The recommended set of values to start with are:
- your CI server's hostname (for triggering builds)
- your company chat (eg. Slack, for publishing notifications)
- your code repository (eg. Github, for sending commit statuses)
Alternatively, you could use a regular expression to limit requests to your company's domain. eg
/.*\.foo\.com$/(don't forget the end of string anchor). You can test Ruby regular expressions at rubular.com.
Behind the scenes, the Pact Broker uses img.shields.io to dynamically create the text on the badges. If the shields.io server cannot be made available to your Pact Broker installation, set
config.shields_io_base_url to nil, and you will get badges with the hardcoded title "pact" instead of "foo/bar pact".
If you cannot allow access to the public shields server because of Network Security, then you could run your own local docker one.
NOTE: If you have added your own authentication on top of the broker, you'll need to add a rule to allow public access to the badge URLs.
version_parser with a lambda or an object/class that responds to call. It should accept a string, and return a sortable object if the version is valid, and nil if the version is not valid.
If you want to customise the error messages to indicate what sort of version format is expected, create a yml file with the following:
By default, pacticipant versions (and hence their related pacts) are sorted by date published. In earlier versions of the Pact Broker, the versions were sorted semantically. Semantic ordering is now not recommended, as the best practice is to publish pacts using the git sha as the consumer version.
You are on a very old version of the Broker, and wish to use date ordering, you will need to set
config.order_versions_by_date = true. After you have restarted, you will need to publish a new pact to trigger a resort, as the ordering is done on insertion.
When a pact is published normally (via a PUT to
consumer version resources are automatically created.
To prevent a pacticipant (consumer or provider) being created multiple times with slightly different name variants (eg. FooBar/foo-bar/foo bar/Foo Bar Service), if a new pacticipant name is deemed similar enough to an existing name, a 409 will be returned. The response body will contain instructions indicating that the pacticipant name should be corrected if it was intended to be an existing one, or that the pacticipant should be created manually if it was intended to be a new one.
To turn this feature off, set
check_for_potential_duplicate_pacticipant_names = false (or set the appropriate environment variable if using a Docker image) in the Pact Broker configuration, and make sure everyone is very careful with their naming! The usefulness of the broker depends on the integrity of the data, which in turn depends on the correctness of the pacticipant names.
Please set the base URL of the Pact Broker application (eg.
https://pact-broker.mycompany.com) via the supported configuration mechanism for the deployment artifact (the environment variable
PACT_BROKER_BASE_URL for the Docker images, or
PactBroker.configuration.base_url = "..." for native Ruby). Setting the base URL is recommended as it prevents some security vulnerabilities associated with dynamically inferring the base URL from the request headers.
2.79.0, multiple base URLs can be configured for architectures that use gateways or proxies that allow the same Pact Broker instance to be addressed with different base URLs. To use this feature, list all the base URLs in the base URL string, separated by a space. eg.
It is preferrable to upgrade to the latest version of the Pact Broker, as 2.46 is old and may contain vulerabilities. Also, determining the base URL dynamically using the X-Forwarded headers leaves the application open to DNS cache poisoning. The following documentation applies if you have no other option however.
If the pact broker is setup behind a reverse proxy then there are a few headers that must be forwarded on for the HAL browser to work properly. The required headers to be sent depend on the proxy configuration. For example if the reverse proxy is configured to forward from https://broker.example.com -> http://internal.broker then X-Forwarded-Host, X-Forwarded-Port and X-Forwarded-Ssl or X-Forwarded-Scheme would need to set in the nginx configuration.
Set this to either "http" or "https" depending on the scheme used by the reverse proxy. For example if the URL configured at the proxy is https://broker.example.com then this should be "https".
Set this to the host name used by the reverse proxy. For example if the URL configured at the proxy is https://broker.example.com then this should be "broker.example.com".
Set this to the port used by the reverse proxy. For example if the URL configured at the proxy is https://broker.example.com then this should be "443".
Set this to "on" if the scheme of the reverse proxy is https. For example if the URL configured at the proxy is https://broker.example.com then this should be "on".
See this example for how to achieve this with Nginx.