capistrano-redmine-deployment 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6bcb935ad7aaa01c101fa9380a958b0dc57a3d6b1b39797fafb3eff6ae03a05
-  data.tar.gz: adaff749719d3b3178b3f6f23e71d9605c8785ff37c773d2422eb2a76f568956
+  metadata.gz: 5586e101b5eda84c25017c252b6a01d26715c4fbab7ee71e609a84a20b7e47cc
+  data.tar.gz: 9e85e888ef2336c3bdc760188cd2d18f10586b1dbabab0367d631f07f4c729da
 SHA512:
-  metadata.gz: c552022bdeac49a92283af11c3e99869efb1509be175ee68179759300c6c3fde2e502b1e096736157f20e4382e77bdd1a934ceb93c6a82a2d736bd544a3ba9c1
-  data.tar.gz: b3d6ae5239ac13d3042f5228ba2a6175a3a0d1b115e186196bf26418d50db3518cb3ea4da397d7c5893f4203db3047ffa3b727ead08e30cddf69f5c25227ac2d
+  metadata.gz: 61c1a9c03f4f60a48f3e4c17f601020b1c6802bee6dcca09d26a1d4f79a777a145696c588dedf0927ddf7e58e665f6cd659653ba033c91ded060555d0e73756e
+  data.tar.gz: e18d575a41748df42b3cb263031fdf6b9152258a5a3bc42f31edf303c15a12f02bbd8cfcb50c5448f27c66a873e26a67c6981fc856a8046ad4aeba45765c2b73

data/README.md

@@ -88,12 +88,24 @@ Setup redmine `API-KEY` through rake-task:
     $ rake capistrano:redmine:deployment:setup
 
 
+## Verifying the setup
+
+Once configured, verify that the credentials, host, project and repository resolve
+to a reachable `redmine_deployment` endpoint:
+
+    $ cap <stage> redmine:verify
+
+This receives a single deployment entry from redmine. A response with **no** entries
+(i.e. no deployment has been logged yet) still counts as a success — it only fails
+when the host is unreachable or the credentials / project / repository are wrong.
+
 ## Redmine requirements
 
 Install the plugin `redmine_deployment`.
 
 ## Features
 * logs (success/failed) deployment to associated redmine repository
+* verifies redmine access / configuration (`redmine:verify`)
 
 -----
 

data/docs/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Capistrano::Redmine::Deployment - CHANGELOG
 
+## [1.2.0] - 2026-07-10
+* **[add]** `redmine:verify` capistrano task to verify config & access by receiving a single deployment
+* **[add]** `Client#receive_deployment` (and `Client.receive_deployment`) - GETs a single deployment entry; an empty (no entries) 2xx response is still treated as valid
+* **[add]** rspec test suite for `Client#receive_deployment`
+
 ## [1.1.0] - 2026-07-10
 * **[add]** ENV layer for config (`REDMINE_API_KEY`, `REDMINE_HOST`, `REDMINE_PROJECT`, `REDMINE_REPOSITORY`, `REDMINE_CA_FILE`)
 * **[add]** `:redmine_api_key` capistrano variable, with `:redmine_api_key_command` (command stdout, e.g. macOS keychain) as fallback

data/lib/capistrano/redmine/deployment/client.rb

@@ -7,37 +7,105 @@ require 'openssl'
 module Capistrano
   module Redmine
     module Deployment
+      # HTTP layer that talks to the Redmine-side +redmine_deployment+ plugin.
+      #
+      # The client POSTs deployment receipts to, and GETs deployment entries
+      # from, +{host}/projects/{project}/deploy/{repository}.json+, authenticating
+      # with an +X-Redmine-API-Key+ header. A response carrying a +deployment+ key
+      # is treated as success; anything else (or an +errors+ array) is a failure.
+      #
+      # All connection details (host, project, repository, api_key, ca_file,
+      # host_verification) are read from the supplied {Config}. SSL is enabled
+      # automatically when the host URI uses the +https+ scheme. Console logging
+      # is on by default and can be turned off via {#silent!} or the +logging:+
+      # initializer flag.
+      #
+      # @example Log a successful deployment
+      #   Client.deploy_success!(config, from_revision: 'abc', to_revision: 'def')
+      #
+      # @example Verify connectivity without writing anything
+      #   Client.receive_deployment(config) # => {"id"=>7, ...}, nil, or false
       class Client
 
+        # @return [Config] the resolved configuration this client reads from.
         attr_reader :config
 
         class << self
+          # Logs a successful deployment.
+          #
+          # Tags the deployment as +'success'+ and POSTs it to Redmine via a
+          # fresh instance.
+          #
+          # @param config [Config] the resolved configuration.
+          # @param deployment [Hash] the deployment payload (mutated in place to
+          #   set +:result+).
+          # @return [Boolean] +true+ when Redmine accepted the deployment.
           def deploy_success!(config, deployment)
             deployment[:result] = 'success'
 
             new(config).deploy!(deployment)
           end
 
+          # Logs a failed deployment.
+          #
+          # Tags the deployment as +'fail'+ and POSTs it to Redmine via a fresh
+          # instance.
+          #
+          # @param config [Config] the resolved configuration.
+          # @param deployment [Hash] the deployment payload (mutated in place to
+          #   set +:result+).
+          # @return [Boolean] +true+ when Redmine accepted the deployment.
           def deploy_fail!(config, deployment)
             deployment[:result] = 'fail'
 
             new(config).deploy!(deployment)
           end
+
+          # Fetches a single deployment entry to verify connectivity.
+          #
+          # Convenience wrapper that builds a fresh instance and delegates to
+          # {#receive_deployment}.
+          #
+          # @param config [Config] the resolved configuration.
+          # @return [Hash, nil, false] the deployment hash, +nil+ when the
+          #   endpoint is reachable but empty, or +false+ on a failed request.
+          def receive_deployment(config)
+            new(config).receive_deployment
+          end
         end
 
+        # @param config [Config] the resolved configuration to read connection
+        #   details and credentials from.
+        # @param logging [Boolean] whether to print progress to STDOUT
+        #   (default +true+). See {#silent!}.
         def initialize(config, logging: true)
           @config = config
           @logging = logging
         end
 
+        # Disables console logging for this client.
+        #
+        # @return [false]
         def silent!
           @logging = false
         end
 
+        # @return [Boolean] whether console logging is currently enabled.
         def log?
           @logging
         end
 
+        # POSTs a deployment receipt to Redmine.
+        #
+        # Logs the outgoing deployment, sends it, and reports the outcome. A
+        # response containing a +deployment+ key counts as success; anything
+        # else is logged as an error.
+        #
+        # @param deployment [Hash] the deployment payload. Recognized keys
+        #   include +:result+, +:from_revision+, +:to_revision+, +:environment+,
+        #   +:branch+ and +:servers+.
+        # @return [Boolean] +true+ when Redmine created the deployment,
+        #   +false+ otherwise.
         def deploy!(deployment)
           log_deploy(deployment) if log?
 
@@ -54,11 +122,98 @@ module Capistrano
           end
         end
 
+        # Receives a single deployment entry from the redmine repository.
+        #
+        # Used to verify that the configured credentials / host / project /
+        # repository actually resolve to a reachable redmine_deployment endpoint.
+        # A successful response with NO entries is still considered valid - it
+        # just means no deployment has been logged yet.
+        #
+        # @return [Hash] the single deployment entry when one exists.
+        # @return [nil] when the endpoint is reachable but has no entries yet.
+        # @return [false] when the request itself failed (non-2xx / errors).
+        def receive_deployment
+          response = fetch_deployments
+
+          return false unless response.is_a?(Hash)
+          return false if response['errors']
+
+          extract_deployment(response)
+        end
+
         private
 
+        # Builds and performs the POST request carrying the deployment payload.
+        #
+        # @param deployment [Hash] the deployment payload to serialize as JSON.
+        # @return [Hash, String] the parsed JSON response, or the raw body when
+        #   it is not valid JSON.
         def send_deployment(deployment)
-          uri = URI("#{config.host}/projects/#{config.project}/deploy/#{config.repository}.json")
+          uri = deploy_uri
+
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request["Content-Type"] = "application/json"
+          request['X-Redmine-API-Key'] = config.api_key
+          request.body = { deployment: deployment }.to_json
+
+          perform(uri, request)
+        end
+
+        # Builds and performs the GET request that fetches deployment entries.
+        #
+        # Requests only a single entry (+limit=1+) since that is all that is
+        # needed to confirm access.
+        #
+        # @return [Hash, String] the parsed JSON response, or the raw body when
+        #   it is not valid JSON.
+        def fetch_deployments
+          uri = deploy_uri
+          # only a single entry is needed to verify access
+          uri.query = 'limit=1'
+
+          request = Net::HTTP::Get.new(uri.request_uri)
+          request["Content-Type"] = "application/json"
+          request['X-Redmine-API-Key'] = config.api_key
 
+          perform(uri, request)
+        end
+
+        # Pulls a single deployment out of an index/show response. The
+        # redmine_deployment plugin may return either a single +deployment+
+        # object or a +deployments+ collection - an empty collection is fine.
+        #
+        # @param response [Object] the parsed response body.
+        # @return [Hash] the +deployment+ object, or the first entry of a
+        #   +deployments+ collection.
+        # @return [nil] when +response+ is not a hash, or when a +deployments+
+        #   collection is empty.
+        def extract_deployment(response)
+          return nil unless response.is_a?(Hash)
+
+          if response['deployment']
+            response['deployment']
+          elsif response['deployments']
+            response['deployments'].first
+          end
+        end
+
+        # @return [URI::Generic] the deploy endpoint URI for the configured
+        #   host / project / repository.
+        def deploy_uri
+          URI("#{config.host}/projects/#{config.project}/deploy/#{config.repository}.json")
+        end
+
+        # Performs an HTTP request, applying SSL and host-verification settings.
+        #
+        # SSL is enabled when the URI scheme is +https+. A configured +ca_file+
+        # takes precedence; otherwise +host_verification == false+ disables peer
+        # verification (the LetsEncrypt/CRL workaround).
+        #
+        # @param uri [URI::Generic] the request target (supplies host/port/scheme).
+        # @param request [Net::HTTPRequest] the prepared request to send.
+        # @return [Hash, Array, String] the parsed JSON response, or the raw body
+        #   when it is not valid JSON.
+        def perform(uri, request)
           http = Net::HTTP.new(uri.host, uri.port)
           http.use_ssl = true if uri.scheme == 'https'
 
@@ -68,11 +223,6 @@ module Capistrano
             http.verify_mode = OpenSSL::SSL::VERIFY_NONE
           end
 
-          request = Net::HTTP::Post.new(uri.request_uri)
-          request["Content-Type"] = "application/json"
-          request['X-Redmine-API-Key'] = config.api_key
-          request.body = { deployment: deployment }.to_json
-
           response = http.request(request)
 
           begin
@@ -82,6 +232,10 @@ module Capistrano
           end
         end
 
+        # Prints the outgoing deployment details (and any SSL warnings) to STDOUT.
+        #
+        # @param deployment [Hash] the deployment payload being sent.
+        # @return [void]
         def log_deploy(deployment)
           puts "Sending deployment information to #{config.host} (project: '#{config.project}' | repo: '#{config.repository}')"
           puts "\e[33m   Using custom CA file: #{config.ca_file}\e[0m" if config.ca_file
@@ -95,11 +249,20 @@ module Capistrano
           puts ""
         end
 
+        # Prints a success line naming the created deployment id.
+        #
+        # @param response [Hash] the parsed success response.
+        # @return [void]
         def log_deploy_done(response)
           puts "\e[32mSuccessfully created deployment ##{response['deployment']['id']}\e[0m"
           puts ""
         end
 
+        # Prints a failure line, listing +errors+ when present or the raw
+        # response otherwise.
+        #
+        # @param response [Object] the parsed failure response.
+        # @return [void]
         def log_deploy_errors(response)
           if response['errors']
             puts "\e[31mFailed to created deployment: #{response['errors'].join(', ')}\e[0m"
@@ -112,5 +275,3 @@ module Capistrano
     end
   end
 end
-
-

data/lib/capistrano/redmine/deployment/gem_version.rb

@@ -10,7 +10,7 @@ module Capistrano
 
       module VERSION
         MAJOR = 1
-        MINOR = 1
+        MINOR = 2
         TINY  = 0
         PRE   = nil
 

data/lib/capistrano/redmine/deployment/tasks/verify.rake

@@ -0,0 +1,57 @@
+namespace :capistrano do
+  namespace :redmine do
+    namespace :deployment do
+      desc <<-END_DESC
+Verify the redmine credentials & access for deployment.
+      END_DESC
+
+      task :verify do
+        require 'capistrano/redmine/deployment/config'
+        require 'capistrano/redmine/deployment/client'
+
+        # resolve configs (from ENV / .redmine file - no capistrano context here)
+        config = Capistrano::Redmine::Deployment::Config.resolve
+
+        puts "******************************************************************************************************"
+        puts "== Capistrano::Redmine::Deployment - verify                                                         =="
+        puts "******************************************************************************************************"
+        puts ""
+        puts " This task verifies your redmine deployment configuration & access."
+        puts " It receives a single deployment entry from the associated redmine repository."
+        puts ""
+        puts " Shared settings are resolved from ENV or the '.redmine' file (host, project,"
+        puts " repository, api_key). Run 'rake capistrano:redmine:deployment:setup' to configure them."
+        puts ""
+        puts "******************************************************************************************************"
+        puts ""
+        puts ""
+
+        # -- BEGIN over here ...
+
+        unless config.valid?
+          puts "\e[31mYour redmine configuration is missing or unfinished.\e[0m"
+          puts "Run 'rake capistrano:redmine:deployment:setup' to configure the credentials."
+          puts ""
+          puts "******************************************************************************************************"
+          puts ""
+          next
+        end
+
+        # An empty result (no deployments logged yet) is fine - `false` means the
+        # request itself failed (unreachable host, bad credentials, wrong project/repo).
+        result = Capistrano::Redmine::Deployment::Client.receive_deployment(config)
+
+        puts ""
+        if result == false
+          puts "\e[31mVerification FAILED. Check host, project, repository and api_key.\e[0m"
+        else
+          puts "\e[32mVerification succeeded.\e[0m"
+        end
+
+        puts ""
+        puts "******************************************************************************************************"
+        puts ""
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: capistrano-redmine-deployment
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Tobias Gonsior
@@ -36,6 +36,7 @@ files:
 - lib/capistrano/redmine/deployment/railtie.rb
 - lib/capistrano/redmine/deployment/receipts.rb
 - lib/capistrano/redmine/deployment/tasks/setup.rake
+- lib/capistrano/redmine/deployment/tasks/verify.rake
 - lib/capistrano/redmine/deployment/version.rb
 homepage: https://github.com/ruby-smart/capistrano-redmine-deployment
 licenses: