capistrano-redmine-deployment 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a1d4def15c15b92236d4cad5e63ab56a469b973763bcaeb0be17a59477efc5e
-  data.tar.gz: 91f5982de00664a05f986f714acd782464c60901d6af1ff051dd7691ecf61032
+  metadata.gz: 5586e101b5eda84c25017c252b6a01d26715c4fbab7ee71e609a84a20b7e47cc
+  data.tar.gz: 9e85e888ef2336c3bdc760188cd2d18f10586b1dbabab0367d631f07f4c729da
 SHA512:
-  metadata.gz: af10737c30d398ab457265538ea359850403e53ec28771ba020cef4a07d178c712aeaafc0a4cbce4d760d9bf81d21938c8b5aa85ef1a95c6e8116aded924a950
-  data.tar.gz: 9d1282a7b24f607c94603b1604138e5d30a18173bbd468be524e39eb8af6c69bf10c47a36703d1868a047a85f9ebc51c65860b0ded0599c3b46f0655db26b1ac
+  metadata.gz: 61c1a9c03f4f60a48f3e4c17f601020b1c6802bee6dcca09d26a1d4f79a777a145696c588dedf0927ddf7e58e665f6cd659653ba033c91ded060555d0e73756e
+  data.tar.gz: e18d575a41748df42b3cb263031fdf6b9152258a5a3bc42f31edf303c15a12f02bbd8cfcb50c5448f27c66a873e26a67c6981fc856a8046ad4aeba45765c2b73

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/Gemfile

@@ -6,3 +6,4 @@ source "https://rubygems.org"
 gemspec
 
 gem "rake"
+gem "rspec"

data/README.md

@@ -49,14 +49,55 @@ set(:redmine_repository, "target-redmine-repository-identifier")
 
 # in case of `SSL` issues that are caused by *CRL* (i.e. by LetsEncrypt certificates)
 set(:redmine_host_verification, false)
+
+# alternatively, for instances with a custom CA, point to a CA bundle instead of
+# disabling verification entirely (preferred over :redmine_host_verification)
+set(:redmine_ca_file, "/path/to/ca-bundle.pem")
 ```
 
 ### User-specific credentials
 
+The `api_key` is resolved from the following sources, **later ones win**:
+
+1. capistrano variables: `:redmine_api_key`, or `:redmine_api_key_command` (its stdout is used as the key) as fallback
+2. `.redmine` file in the current directory (`$PWD`) or `$HOME`
+3. the `REDMINE_API_KEY` ENV variable
+
+#### Option A: macOS Keychain (recommended)
+
+Store the key once per developer in the keychain (use a dedicated entry):
+
+    $ security add-generic-password -s ri-redmine-deploy -a "$USER" -w 'YOUR_KEY'
+
+Then point capistrano at a command that reads it, in your `config/deploy.rb`:
+
+```ruby
+set :redmine_api_key_command, 'security find-generic-password -s ri-redmine-deploy -w'
+```
+
+No secret ends up in `deploy.rb` or your SCM — only the command. Once every developer
+has switched over, the `.redmine` file can be removed entirely (it stays supported as a
+fallback).
+
+> Use a **dedicated** keychain entry (e.g. `ri-redmine-deploy`).
+
+#### Option B: `.redmine` file via rake-task
+
 Setup redmine `API-KEY` through rake-task:
 
-    $ rake capistrano:redmine:deploy:setup
+    $ 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
 
@@ -64,6 +105,7 @@ 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,18 @@
 # 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
+* **[add]** `:redmine_ca_file` config (and `REDMINE_CA_FILE` ENV) as a safe alternative to disabling host verification
+* **[add]** rspec test suite for `Config.resolve` layer precedence
+* **[ref]** config resolution order: capistrano is the base, then `.redmine` files, then ENV win over it
+* **[fix]** enable SSL by URI scheme (`https`) instead of only port 443, so HTTPS on non-standard ports works
+
 ## [1.0.1] - 2025-10-24
 * **[add]** config for `host_verification` to skip issues with OpenSSL / CRL issues
 * **[add]** warning message during deployment while host verification is disabled

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,20 +122,107 @@ 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")
-
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.use_ssl = true if uri.port == 443
-          http.verify_mode = OpenSSL::SSL::VERIFY_NONE if config.host_verification == false
+          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'
+
+          if config.ca_file
+            http.ca_file = config.ca_file
+          elsif config.host_verification == false
+            http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+          end
+
           response = http.request(request)
 
           begin
@@ -77,9 +232,14 @@ 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   WARNING: Host verification disabled!\e[0m" if config.host_verification == false
+          puts "\e[33m   Using custom CA file: #{config.ca_file}\e[0m" if config.ca_file
+          puts "\e[33m   WARNING: Host verification disabled!\e[0m" if config.ca_file.nil? && config.host_verification == false
           puts ""
           puts "   Commits......: #{deployment[:from_revision]} ... #{deployment[:to_revision]}"
           puts "   Environment..: #{deployment[:environment] || '-'}"
@@ -89,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"
@@ -106,5 +275,3 @@ module Capistrano
     end
   end
 end
-
-

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

@@ -14,7 +14,7 @@ module Capistrano
             # build new empty config
             config = new
 
-            # try to resolve from capistrano
+            # capistrano is the base - files and ENV win over it
             config.assign!(config_from_capistrano(capistrano)) if capistrano
 
             # try to resolve from current PWD
@@ -22,23 +22,58 @@ module Capistrano
             config.assign!(config_from_file(File.join(ENV['HOME'], '.redmine')))
             config.assign!(config_from_file(file)) if file
 
+            # ENV wins over files and capistrano
+            config.assign!(config_from_env)
+
             config
           end
 
           def config_from_capistrano(capistrano)
             config = {
+              api_key: capistrano.fetch(:redmine_api_key) || api_key_from_command(capistrano),
               host: capistrano.fetch(:redmine_host),
               project: capistrano.fetch(:redmine_project) || capistrano.fetch(:redmine_project_id),
               repository: capistrano.fetch(:redmine_repository),
-              host_verification: capistrano.fetch(:redmine_host_verification)
+              host_verification: capistrano.fetch(:redmine_host_verification),
+              ca_file: capistrano.fetch(:redmine_ca_file)
             }
 
             new(config)
           end
 
+          # Resolves config from ENV variables. Values are filtered by `assign!`,
+          # so unset (nil/empty) variables never overwrite an existing value.
+          def config_from_env
+            new({
+              api_key:    ENV['REDMINE_API_KEY'],
+              host:       ENV['REDMINE_HOST'],
+              project:    ENV['REDMINE_PROJECT'],
+              repository: ENV['REDMINE_REPOSITORY'],
+              ca_file:    ENV['REDMINE_CA_FILE']
+            })
+          end
+
           def config_from_file(file)
             new(file: file)
           end
+
+          private
+
+          # Resolves the api_key by running the `:redmine_api_key_command` capistrano
+          # variable (if set) and taking its stdout. This keeps the secret out of
+          # `deploy.rb` - only the command (e.g. a keychain lookup) lives there.
+          #
+          # On any failure (non-zero exit or empty stdout) nil is returned so the
+          # file/ENV fallback still applies.
+          def api_key_from_command(capistrano)
+            cmd = capistrano.fetch(:redmine_api_key_command)
+            return nil unless cmd && cmd != ''
+
+            key = `#{cmd}`.strip
+            return nil unless $?.success? && !key.empty?
+
+            key
+          end
         end
 
         def initialize(config = {}, file: nil)

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

@@ -10,8 +10,8 @@ module Capistrano
 
       module VERSION
         MAJOR = 1
-        MINOR = 0
-        TINY  = 1
+        MINOR = 2
+        TINY  = 0
         PRE   = nil
 
         STRING = [MAJOR, MINOR, TINY, PRE].compact.join(".")

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

@@ -24,6 +24,11 @@ Configure the redmine credentials for deployment.
         puts ""
         puts " > HINT: Keep configs empty to prevent to overwrite existing configs."
         puts ""
+        puts " > ALTERNATIVE (recommended): the api_key can also be provided without this file"
+        puts "   via the ENV variable 'REDMINE_API_KEY' or the capistrano variable"
+        puts "   ':redmine_api_key_command' (e.g. a macOS keychain lookup). Both win over"
+        puts "   the '.redmine' file. See the README for details."
+        puts ""
         puts "******************************************************************************************************"
         puts ""
         puts ""

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.0.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Tobias Gonsior
@@ -19,6 +19,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rspec"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -35,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: