pact_broker-client 1.47.0 → 1.50.0

data/doc/CAN_I_DEPLOY_USAGE_WITH_TAGS.md

@@ -0,0 +1,107 @@
+# Using can-i-deploy with tags
+
+The can-i-deploy tool was originally written to support specifying versions and dependencies using tags. This usage has now been superseded by first class support for [environments, deployments and releases](https://docs.pact.io/pact_broker/recording_deployments_and_releases/).
+
+The following documentation covers the usage of can-i-deploy for users who are still using tags to track environments and deployments.
+
+There are two ways to use `can-i-deploy` with tags. The first (recommended and most commonly used) approach is to specify just the application version you want to deploy and let the Pact Broker work out the dependencies for you. The second approach is to specify each application version explicitly. This would generally only be used if there were limitations that stopped you being able to use the first approach.
+
+#### Specifying an application version
+
+To specify an application (pacticipant) version you need to provide:
+
+* the name of the application using the `--pacticipant PACTICIPANT` parameter,
+* directly followed by *one* of the following parameters:
+    * `--version VERSION` to specify a known application version (recommended)
+    * `--latest` to specify the latest version
+    * `--latest TAG` to specify the latest version that has a particular tag
+    * `--all TAG` to specify all the versions that have a particular tag (eg. "all prod" versions). This would be used when ensuring you have backwards compatiblity with all production mobile clients for a provider. Note, when using this option, you need to specify dependency explicitly (see the second usage option).
+
+Using a specific version is the easiest way to ensure you get an accurate response that won't be affected by race conditions.
+
+#### Recommended usage - allowing the Pact Broker to automatically determine the dependencies
+
+Prerequisite: if you would like the Pact Broker to calculate the dependencies for you when you want to deploy an application into a given environment, you will need to let the Broker know which version of each application is in that environment.
+
+How you do this depends on the version of the Pact Broker you are running.
+
+If you are using a Broker version where deployment versions are supported, then you would notify the Broker of the deployment of this application version like so:
+
+    $ pact-broker record-deployment --pacticipant Foo --version 173153ae0 --environment test
+
+This assumes that you have already set up an environment named "test" in the Broker.
+
+If you are using a Broker version that does not support deployment environments, then you will need to use tags to notify the broker of the deployment of this application version, like so:
+
+    $ pact-broker create-version-tag --pacticipant Foo --version 173153ae0 --tag test
+
+Once you have configured your build to notify the Pact Broker of the successful deployment using either method describe above, you can use the following simple command to find out if you are safe to deploy (use either `--to` or  `--to-environment` as supported):
+
+    $ pact-broker can-i-deploy --pacticipant PACTICIPANT --version VERSION
+                               [--to-environment ENVIRONMENT | --to ENVIRONMENT_TAG ]
+                               --broker-base-url BROKER_BASE_URL
+
+If the `--to` or `--to-environment` options are omitted, then the query will return the compatiblity with the overall latest version of each of the other applications.
+
+Examples:
+
+
+Can I deploy version 173153ae0 of application Foo to the test environment?
+
+
+    $ pact-broker can-i-deploy --pacticipant Foo --version 173153ae0 \
+                               --to-environment test \
+                               --broker-base-url https://my-pact-broker
+
+
+Can I deploy the latest version of application Foo with the latest version of each of the applications it integrates to?
+
+
+    $ pact-broker can-i-deploy --pacticipant Foo --latest \
+                               --broker-base-url https://my-pact-broker
+
+
+Can I deploy the latest version of the application Foo that has the tag "test" to the "prod" environment?
+
+    $ pact-broker can-i-deploy --pacticipant Foo --latest test \
+                               --to prod \
+                               --broker-base-url https://my-pact-broker
+
+
+#### Alternate usage - specifying dependencies explicitly
+
+If you are unable to use tags, or there is some other limitation that stops you from using the recommended approach, you can specify one or more of the dependencies explictly. You must also do this if you want to use the `--all TAG` option for any of the pacticipants.
+
+You can specify as many application versions as you like, and you can even specify multiple versions of the same application (repeat the `--pacticipant` name and supply a different version.)
+
+You can use explictly declared dependencies with or without the `--to ENVIRONMENT_TAG`. For example, if you declare two (or more) application versions with no `--to ENVIRONMENT_TAG`, then only the applications you specify will be taken into account when determining if it is safe to deploy. If you declare two (or more) application versions _as well as_ a `--to ENVIRONMENT`, then the Pact Broker will work out what integrations your declared applications will have in that environment when determining if it safe to deploy. When using this script for a production release, and you are using tags, it is always the most future-proof option to use the `--to` if possible, as it will catch any newly added consumers or providers.
+
+If you are finding that your dependencies are not being automatically included when you supply multiple pacticipant versions, please upgrade to the latest version of the Pact Broker, as this is a more recently added feature.
+
+
+    $ pact-broker can-i-deploy --pacticipant PACTICIPANT_1 [--version VERSION_1 | --latest [TAG_1] | --all TAG_1] \
+                               --pacticipant PACTICIPANT_2 [--version VERSION_2 | --latest [TAG_2] | --all TAG_2] \
+                               [--to-environment ENVIRONMENT | --to ENVIRONMENT_TAG]
+
+Examples:
+
+
+Can I deploy version Foo version 173153ae0 and Bar version ac23df1e8 together?
+
+
+    $ pact-broker can-i-deploy --pacticipant Foo --version 173153ae0 \
+                               --pacticipant Bar --version ac23df1e8
+
+
+Can I deploy the latest version of Foo with tag "master" and the latest version of Bar with tag "master" together?
+
+    $ pact-broker can-i-deploy --pacticipant Foo --latest master \
+                               --pacticipant Bar --latest master
+
+
+Mobile provider use case - can I deploy version b80e7b1b of Bar, all versions of Foo with tag "prod", and the latest version tagged "prod" of any other automatically calculated dependencies together? (Eg. where Bar is a provider and Foo is a mobile consumer with multiple versions in production, and Bar also has its own providers it needs to be compatible with.)
+
+
+    $ pact-broker can-i-deploy --pacticipant Bar --version b80e7b1b \
+                               --pacticipant Foo --all prod \
+                               --to prod

data/doc/pacts/markdown/Pact Broker Client - Pact Broker.md

@@ -1159,7 +1159,6 @@ Pact Broker will respond with:
   },
   "body": {
     "number": "26f353580936ad3b9baddb17b00e84f33c69e7cb",
-    "branch": "main",
     "buildUrl": "http://my-ci/builds/1",
     "_links": {
       "self": {
@@ -1194,7 +1193,6 @@ Pact Broker will respond with:
   },
   "body": {
     "number": "26f353580936ad3b9baddb17b00e84f33c69e7cb",
-    "branch": "main",
     "buildUrl": "http://my-ci/builds/1",
     "_links": {
       "self": {

data/example/scripts/verify-changed-pact.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# Use this to stop unnecessary verifications from running when triggered by the
+# `contract_content_changed` webhook, or when using the webhookless flow.
+
+set -eu
+
+PACT_CLI_VERSION="0.47.0.0"
+
+: "${PACT_URL:?PACT_URL is not set, cannot run verification.}"
+: "${CONSUMER_NAME:?CONSUMER_NAME is not set, cannot check if verification is required.}"
+: "${CONSUMER_VERSION_NUMBER:?CONSUMER_VERSION_NUMBER is not set, cannot check if verification is required.}"
+
+# Delete unnecessary username/password/token
+if docker run --rm \
+    -e PACT_BROKER_BASE_URL \
+    -e PACT_BROKER_TOKEN \
+    -e PACT_BROKER_USERNAME \
+    -e PACT_BROKER_PASSWORD \
+    -e PACT_BROKER_FEATURES="verification_required" \
+    -it \
+    pactfoundation/pact-cli:$PACT_CLI_VERSION \
+      broker verification-required \
+      --pacticipant pactflow-application-saas \
+      --version ${RELEASE_VERSION} \
+      --pacticipant ${CONSUMER_NAME} \
+      --version ${CONSUMER_VERSION_NUMBER} \
+      --verbose ; then
+  echo "Run the verification here"
+fi

data/lib/pact_broker/client/cli/can_i_deploy_long_desc.txt

@@ -1,109 +1,24 @@
-Returns exit code 0 or 1, indicating whether or not the specified application (pacticipant) versions are compatible (ie. safe to deploy). Prints out the relevant pact/verification details, indicating any missing or failed verification results.
+Returns exit code 0 or 1, indicating whether or not the specified application (pacticipant) has a successful verification result with each of the application versions that are already deployed to a particular environment. Prints out the relevant pact/verification details, indicating any missing or failed verification results.
 
-The environment variables PACT_BROKER_BASE_URL, PACT_BROKER_USERNAME and PACT_BROKER_PASSWORD may be used instead of their respective command line options.
+The can-i-deploy tool was originally written to support specifying versions and dependencies using tags. This usage has now been superseded by first class support for environments, deployments and releases. For documentation on how to use can-i-deploy with tags, please see https://docs.pact.io/pact_broker/client_cli/can_i_deploy_usage_with_tags/
 
-There are two ways to use `can-i-deploy`. The first (recommended and most commonly used) approach is to specify just the application version you want to deploy and let the Pact Broker work out the dependencies for you. The second approach is to specify each application version explicitly. This would generally only be used if there were limitations that stopped you being able to use the first approach.
+Before `can-i-deploy` can be used, the relevant environment resources must first be created in the Pact Broker using the `create-environment` command. The "test" and "production" environments will have been seeded for you. You can check the existing environments by running `pact-broker list-environments`. See https://docs.pact.io/pact_broker/client_cli/readme#environments for more information.
 
-#### Specifying an application version
+    $ pact-broker create-environment --name "uat" --display-name "UAT" --no-production
 
-To specify an application (pacticipant) version you need to provide:
+After an application is deployed or released, its deployment must be recorded using the `record-deployment` or `record-release` commands. See https://docs.pact.io/pact_broker/recording_deployments_and_releases/ for more information.
 
-* the name of the application using the `--pacticipant PACTICIPANT` parameter,
-* directly followed by *one* of the following parameters:
-    * `--version VERSION` to specify a known application version (recommended)
-    * `--latest` to specify the latest version
-    * `--latest TAG` to specify the latest version that has a particular tag
-    * `--all TAG` to specify all the versions that have a particular tag (eg. "all prod" versions). This would be used when ensuring you have backwards compatiblity with all production mobile clients for a provider. Note, when using this option, you need to specify dependency explicitly (see the second usage option).
+    $ pact-broker record-deployment --pacticipant Foo --version 173153ae0 --environment uat
 
-Using a specific version is the easiest way to ensure you get an accurate response that won't be affected by race conditions.
+Before an application is deployed or released to an environment, the can-i-deploy command must be run to check that the application version is safe to deploy with the versions of each integrated application that are already in that environment.
 
-#### Recommended usage - allowing the Pact Broker to automatically determine the dependencies
+    $ pact-broker can-i-deploy --pacticipant PACTICIPANT --version VERSION --to-environment ENVIRONMENT
 
-Prerequisite: if you would like the Pact Broker to calculate the dependencies for you when you want to deploy an application into a given environment, you will need to let the Broker know which version of each application is in that environment.
+Example: can I deploy version 173153ae0 of application Foo to the test environment?
 
-How you do this depends on the version of the Pact Broker you are running.
+    $ pact-broker can-i-deploy --pacticipant Foo --version 173153ae0 --to-environment test
 
-If you are using a Broker version where deployment versions are supported, then you would notify the Broker of the deployment of this application version like so:
+Can-i-deploy can also be used to check if arbitrary versions have a successful verification. When asking "Can I deploy this application version with the latest version from the main branch of another application" it functions as a "can I merge" check.
 
-    $ pact-broker record-deployment --pacticipant Foo --version 173153ae0 --environment test
-
-This assumes that you have already set up an environment named "test" in the Broker.
-
-If you are using a Broker version that does not support deployment environments, then you will need to use tags to notify the broker of the deployment of this application version, like so:
-
-    $ pact-broker create-version-tag --pacticipant Foo --version 173153ae0 --tag test
-
-Once you have configured your build to notify the Pact Broker of the successful deployment using either method describe above, you can use the following simple command to find out if you are safe to deploy (use either `--to` or  `--to-environment` as supported):
-
-    $ pact-broker can-i-deploy --pacticipant PACTICIPANT --version VERSION
-                               [--to-environment ENVIRONMENT | --to ENVIRONMENT_TAG ]
-                               --broker-base-url BROKER_BASE_URL
-
-If the `--to` or `--to-environment` options are omitted, then the query will return the compatiblity with the overall latest version of each of the other applications.
-
-Examples:
-
-
-Can I deploy version 173153ae0 of application Foo to the test environment?
-
-
-    $ pact-broker can-i-deploy --pacticipant Foo --version 173153ae0 \
-                               --to-environment test \
-                               --broker-base-url https://my-pact-broker
-
-
-Can I deploy the latest version of application Foo with the latest version of each of the applications it integrates to?
-
-
-    $ pact-broker can-i-deploy --pacticipant Foo --latest \
-                               --broker-base-url https://my-pact-broker
-
-
-Can I deploy the latest version of the application Foo that has the tag "test" to the "prod" environment?
-
-    $ pact-broker can-i-deploy --pacticipant Foo --latest test \
-                               --to prod \
-                               --broker-base-url https://my-pact-broker
-
-
-#### Alternate usage - specifying dependencies explicitly
-
-If you are unable to use tags, or there is some other limitation that stops you from using the recommended approach, you can specify one or more of the dependencies explictly. You must also do this if you want to use the `--all TAG` option for any of the pacticipants.
-
-You can specify as many application versions as you like, and you can even specify multiple versions of the same application (repeat the `--pacticipant` name and supply a different version.)
-
-You can use explictly declared dependencies with or without the `--to ENVIRONMENT_TAG`. For example, if you declare two (or more) application versions with no `--to ENVIRONMENT_TAG`, then only the applications you specify will be taken into account when determining if it is safe to deploy. If you declare two (or more) application versions _as well as_ a `--to ENVIRONMENT`, then the Pact Broker will work out what integrations your declared applications will have in that environment when determining if it safe to deploy. When using this script for a production release, and you are using tags, it is always the most future-proof option to use the `--to` if possible, as it will catch any newly added consumers or providers.
-
-If you are finding that your dependencies are not being automatically included when you supply multiple pacticipant versions, please upgrade to the latest version of the Pact Broker, as this is a more recently added feature.
-
-
-    $ pact-broker can-i-deploy --pacticipant PACTICIPANT_1 [--version VERSION_1 | --latest [TAG_1] | --all TAG_1] \
-                               --pacticipant PACTICIPANT_2 [--version VERSION_2 | --latest [TAG_2] | --all TAG_2] \
-                               [--to-environment ENVIRONMENT | --to ENVIRONMENT_TAG] \
-                               --broker-base-url BROKER_BASE_URL
-
-Examples:
-
-
-Can I deploy version Foo version 173153ae0 and Bar version ac23df1e8 together?
-
-
-    $ pact-broker can-i-deploy --pacticipant Foo --version 173153ae0 \
-                               --pacticipant Bar --version ac23df1e8 \
-                               --broker-base-url BROKER_BASE_URL
-
-
-Can I deploy the latest version of Foo with tag "master" and the latest version of Bar with tag "master" together?
-
-    $ pact-broker can-i-deploy --pacticipant Foo --latest master \
-                               --pacticipant Bar --latest master \
-                               --broker-base-url BROKER_BASE_URL
-
-
-Mobile provider use case - can I deploy version b80e7b1b of Bar, all versions of Foo with tag "prod", and the latest version tagged "prod" of any other automatically calculated dependencies together? (Eg. where Bar is a provider and Foo is a mobile consumer with multiple versions in production, and Bar also has its own providers it needs to be compatible with.)
-
-
-    $ pact-broker can-i-deploy --pacticipant Bar --version b80e7b1b \
-                               --pacticipant Foo --all prod \
-                               --to prod \
-                               --broker-base-url BROKER_BASE_URL
+    $ pact-broker can-i-deploy --pacticipant Foo 173153ae0 \
+                               --pacticipant Bar --latest main

data/lib/pact_broker/client/cli/environment_commands.rb

@@ -38,7 +38,7 @@ module PactBroker
               execute_environment_command(params_from_options([:uuid]), "DescribeEnvironment")
             end
 
-            desc "list-environments", "List environment"
+            desc "list-environments", "List environments"
             method_option :output, aliases: "-o", desc: "json or text", default: 'text'
             shared_authentication_options
             def list_environments

data/lib/pact_broker/client/cli/matrix_commands.rb

@@ -12,8 +12,8 @@ module PactBroker
             method_option :version, required: false, aliases: "-e", desc: "The pacticipant version. Must be entered after the --pacticipant that it relates to."
             method_option :ignore, required: false, desc: "The pacticipant name to ignore. Use once for each pacticipant being ignored. A specific version can be ignored by also specifying a --version after the pacticipant name option."
             method_option :latest, required: false, aliases: "-l", banner: "[TAG]", desc: "Use the latest pacticipant version. Optionally specify a TAG to use the latest version with the specified tag."
-            method_option :to, required: false, banner: "TAG", desc: "This is too hard to explain in a short sentence. Look at the examples.", default: nil
-            method_option :to_environment, required: false, banner: "ENVIRONMENT", desc: "The environment into which the pacticipant(s) are to be deployed", default: nil, hide: true
+            method_option :to_environment, required: false, banner: "ENVIRONMENT", desc: "The environment into which the pacticipant(s) are to be deployed", default: nil
+            method_option :to, required: false, banner: "TAG", desc: "The tag that represents the branch or environment of the integrated applications for which you want to check the verification result status.", default: nil
             method_option :output, aliases: "-o", desc: "json or table", default: "table"
             method_option :retry_while_unknown, banner: "TIMES", type: :numeric, default: 0, required: false, desc: "The number of times to retry while there is an unknown verification result (ie. the provider verification is likely still running)"
             method_option :retry_interval, banner: "SECONDS", type: :numeric, default: 10, required: false, desc: "The time between retries in seconds. Use in conjuction with --retry-while-unknown"
@@ -28,11 +28,7 @@ module PactBroker
 
               validate_credentials
               selectors = VersionSelectorOptionsParser.call(ARGV).select { |s| !s[:ignore] }
-              ignore_selectors = if ENV.fetch("PACT_BROKER_FEATURES", "").include?("ignore")
-                VersionSelectorOptionsParser.call(ARGV).select { |s| s[:ignore] }
-              else
-                []
-              end
+              ignore_selectors = VersionSelectorOptionsParser.call(ARGV).select { |s| s[:ignore] }
               validate_can_i_deploy_selectors(selectors)
               dry_run = options.dry_run || ENV["PACT_BROKER_CAN_I_DEPLOY_DRY_RUN"] == "true"
               can_i_deploy_options = { output: options.output, retry_while_unknown: options.retry_while_unknown, retry_interval: options.retry_interval, dry_run: dry_run, verbose: options.verbose }

data/lib/pact_broker/client/cli/webhook_commands.rb

@@ -22,6 +22,9 @@ module PactBroker
                 method_option :provider_verification_published, type: :boolean, desc: "Trigger this webhook when a provider verification result is published"
                 method_option :provider_verification_failed, type: :boolean, desc: "Trigger this webhook when a failed provider verification result is published"
                 method_option :provider_verification_succeeded, type: :boolean, desc: "Trigger this webhook when a successful provider verification result is published"
+                if ENV.fetch("PACT_BROKER_FEATURES", "").include?("contract_requiring_verification_published")
+                  method_option :contract_requiring_verification_published, type: :boolean, desc: "Trigger this webhook when a contract is published that requires verification"
+                end
                 method_option :team_uuid, banner: "UUID", desc: "UUID of the Pactflow team to which the webhook should be assigned (Pactflow only)"
                 shared_authentication_options
               end
@@ -62,12 +65,14 @@ module PactBroker
                 events << 'provider_verification_published' if options.provider_verification_published
                 events << 'provider_verification_succeeded' if options.provider_verification_succeeded
                 events << 'provider_verification_failed' if options.provider_verification_failed
+                events << 'contract_requiring_verification_published' if options.contract_requiring_verification_published
                 events
               end
 
               def parse_webhook_options(webhook_url)
                 events = parse_webhook_events
 
+                # TODO update for contract_requiring_verification_published when released
                 if events.size == 0
                   raise WebhookCreationError.new("You must specify at least one of --contract-content-changed, --contract-published, --provider-verification-published, --provider-verification-succeeded or --provider-verification-failed")
                 end

data/lib/pact_broker/client/matrix/abbreviate_version_number.rb

@@ -2,11 +2,33 @@ module PactBroker
   module Client
     class Matrix
       class AbbreviateVersionNumber
-        def self.call version_number
-          if version_number
-            version_number.gsub(/[A-Za-z0-9]{40}/) do | val |
-              val[0...7] + "..."
-            end
+        # Official regex from https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+        SEMVER_REGEX = /(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?/
+        SHA1_REGEX = /[A-Za-z0-9]{40}/
+
+        class << self
+          def call version_number
+            return unless version_number
+
+            return replace_all_git_sha(version_number) if [SEMVER_REGEX, SHA1_REGEX].all?{|r| regex_match?(r, version_number) }
+
+            return replace_all_git_sha(version_number) if regex_match?(Regexp.new("\\A#{SHA1_REGEX.source}\\z"), version_number)
+
+            # Trim to some meaningful value in case we couldn't match anything, just not to mess with the output
+            return version_number[0...60] + '...' if version_number.length > 60
+
+            version_number
+          end
+
+          private
+
+          # To support ruby2.2
+          def regex_match?(regex, value)
+            !regex.match(value).nil?
+          end
+
+          def replace_all_git_sha(version)
+            version.gsub(SHA1_REGEX) { |val| val[0...7] + '...' }
           end
         end
       end

data/lib/pact_broker/client/matrix/resource.rb

@@ -30,6 +30,10 @@ module PactBroker
           end
         end
 
+        def no_results?
+          self[:summary][:success] == 0 && self[:summary][:failed] == 0
+        end
+
         def supports_unknown_count?
           !!(self[:summary] && Integer === self[:summary][:unknown] )
         end

data/lib/pact_broker/client/verification_required.rb

@@ -17,7 +17,9 @@ module PactBroker
 
       def create_result(matrix)
         matrix_and_notices = format_matrix(matrix) + "\n\n" + remove_warnings(Term::ANSIColor.uncolor(notice_or_reason(matrix, :white)))
-        if matrix.any_unknown?
+        # If the specified version numbers do not exist, then all the counts come back 0. Can't just check for unknown to be 0.
+        # This command needs to handle "I screwed up the query"
+        if matrix.no_results?
           Result.new(true, matrix_and_notices + "\n\nVerification is required.")
         else
           Result.new(false, matrix_and_notices + "\n\nNo verification is required.")

data/lib/pact_broker/client/version.rb

@@ -1,5 +1,5 @@
 module PactBroker
   module Client
-    VERSION = '1.47.0'
+    VERSION = '1.50.0'
   end
 end

data/script/update-cli-usage-in-readme.rb

@@ -0,0 +1,152 @@
+#!/usr/bin/env ruby
+require "stringio"
+require "pact_broker/client/cli/broker"
+
+ENV["THOR_COLUMNS"] = "160"
+START_MARKER = "<!-- start-autogenerated-docs -->"
+END_MARKER = "<!-- end-autogenerated-docs -->"
+TERMINAL_WIDTH = 80
+
+def print_wrapped(message, options = {})
+  out = StringIO.new
+  indent = options[:indent] || 0
+  width = TERMINAL_WIDTH - indent
+  paras = message.split("\n\n")
+
+  paras.map! do |unwrapped|
+    counter = 0
+    unwrapped.split(" ").inject do |memo, word|
+      word = word.gsub(/\n\005/, "\n").gsub(/\005/, "\n")
+      counter = 0 if word.include? "\n"
+      if (counter + word.length + 1) < width
+        memo = "#{memo} #{word}"
+        counter += (word.length + 1)
+      else
+        memo = "#{memo}\n#{word}"
+        counter = word.length
+      end
+      memo
+    end
+  end.compact!
+
+  paras.each do |para|
+    para.split("\n").each do |line|
+      out.puts line.insert(0, " " * indent)
+    end
+    out.puts unless para == paras.last
+  end
+  out.string
+end
+
+def format_banner(banner)
+  banner_lines = print_wrapped(banner, indent: 16).split("\n")
+  banner_lines[0] = banner_lines[0].gsub(/^\s\s/, "")
+  banner_lines
+end
+
+def generate_thor_docs
+  begin
+    out = StringIO.new
+    $stdout = out
+
+    command_groups = [
+      ["Pacts", %w[publish list-latest-pact-versions] ],
+      ["Environments", %w[create-environment update-environment describe-environment delete-environment list-environments]],
+      ["Deployments", %w[record-deployment record-undeployment]],
+      ["Releases", %w[record-release record-support-ended]],
+      ["Matrix", %w[can-i-deploy]],
+      ["Pacticipants", %w[create-or-update-pacticipant describe-pacticipant list-pacticipants]],
+      ["Webhooks", %w[create-webhook create-or-update-webhook test-webhook]],
+      ["Tags", %w[create-version-tag]],
+      ["Versions", %w[describe-version]],
+      ["Miscellaneous", %w[generate-uuid]]
+    ]
+
+    command_groups.collect do | group, commands |
+      puts "### #{group}\n\n"
+      commands.each do | command |
+        puts "#### #{command}\n\n"
+        PactBroker::Client::CLI::Broker.start(["help", command])
+        puts "\n"
+      end
+    end
+    out.string
+  ensure
+    $stdout = STDOUT
+  end
+end
+
+STATES = {
+  start: {
+    /^Usage:/ => :usage
+  },
+  usage: {
+    /^Options:/ => :options
+  },
+  options: {
+    /^$/ => :after_options
+  },
+  after_options: {
+    /^Usage:/ => :usage
+  }
+}
+
+def entered?(state)
+  @old_state != state && @current_state == state
+end
+
+def exited?(state)
+  @old_state == state && @current_state != state
+end
+
+def has_option_and_banner(line)
+  line =~ /--.*\s#\s/
+end
+
+def has_only_banner(line)
+  line =~ /^\s+#\s/
+end
+
+@current_state = :start
+@old_state = nil
+
+def reformat_docs(generated_thor_docs)
+  generated_thor_docs.split("\n").collect do | line |
+    @old_state = @current_state
+
+    transitions = STATES[@current_state]
+
+    line_starts_with = transitions.keys.find { | key |  line =~ key }
+    if line_starts_with
+      @current_state = transitions[line_starts_with]
+    end
+
+
+    lines = if has_option_and_banner(line)
+      option, banner = line.split("#", 2)
+      [option] + format_banner("# " + banner)
+    elsif has_only_banner(line)
+      space, banner = line.split("#", 2)
+      format_banner("#  " + banner)
+    else
+      [line]
+    end
+
+    if entered?(:usage) || exited?(:options)
+      ["```"] + lines
+    else
+      lines
+    end
+    # line
+  end.flatten.join("\n").gsub("/go/", "/").gsub(File.basename(__FILE__), "pact-broker")
+end
+
+def update_readme(usage_docs)
+  readme_text = File.read("README.md")
+  before_text = readme_text.split(START_MARKER).first
+  after_text = readme_text.split("<!-- end-autogenerated-docs -->", 2).last
+  new_readme_text = before_text + START_MARKER + "\n\n" + usage_docs + "\n\n" + END_MARKER + after_text
+  File.open("README.md", "w") { |file| file << new_readme_text }
+end
+
+update_readme(reformat_docs(generate_thor_docs))