Class: Capistrano::Redmine::Deployment::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/capistrano/redmine/deployment/client.rb

Overview

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.

Examples:

Log a successful deployment

Client.deploy_success!(config, from_revision: 'abc', to_revision: 'def')

Verify connectivity without writing anything

Client.receive_deployment(config) # => {"id"=>7, ...}, nil, or false

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config, logging: true) ⇒ Client

Returns a new instance of Client.

Parameters:

  • config (Config) —

    the resolved configuration to read connection details and credentials from.

  • logging (Boolean) (defaults to: true) —

    whether to print progress to STDOUT (default true). See #silent!.



81
82
83
84
 
# File 'lib/capistrano/redmine/deployment/client.rb', line 81

def initialize(config, logging: true)
  @config = config
  @logging = logging
end

Instance Attribute Details

#config ⇒ Config (readonly)

Returns the resolved configuration this client reads from.

Returns:

  • (Config) —

    the resolved configuration this client reads from.



31
32
33
 
# File 'lib/capistrano/redmine/deployment/client.rb', line 31

def config
  @config
end

Class Method Details

.deploy_fail!(config, deployment) ⇒ Boolean

Logs a failed deployment.

Tags the deployment as 'fail' and POSTs it to Redmine via a fresh instance.

Parameters:

  • config (Config) —

    the resolved configuration.

  • deployment (Hash) —

    the deployment payload (mutated in place to set :result).

Returns:

  • (Boolean) —

    true when Redmine accepted the deployment.



58
59
60
61
62
 
# File 'lib/capistrano/redmine/deployment/client.rb', line 58

def deploy_fail!(config, deployment)
  deployment[:result] = 'fail'

  new(config).deploy!(deployment)
end

.deploy_success!(config, deployment) ⇒ Boolean

Logs a successful deployment.

Tags the deployment as 'success' and POSTs it to Redmine via a fresh instance.

Parameters:

  • config (Config) —

    the resolved configuration.

  • deployment (Hash) —

    the deployment payload (mutated in place to set :result).

Returns:

  • (Boolean) —

    true when Redmine accepted the deployment.



43
44
45
46
47
 
# File 'lib/capistrano/redmine/deployment/client.rb', line 43

def deploy_success!(config, deployment)
  deployment[:result] = 'success'

  new(config).deploy!(deployment)
end

.receive_deployment(config) ⇒ Hash, ...

Fetches a single deployment entry to verify connectivity.

Convenience wrapper that builds a fresh instance and delegates to #receive_deployment.

Parameters:

  • config (Config) —

    the resolved configuration.

Returns:

  • (Hash, nil, false) —

    the deployment hash, nil when the endpoint is reachable but empty, or false on a failed request.



72
73
74
 
# File 'lib/capistrano/redmine/deployment/client.rb', line 72

def receive_deployment(config)
  new(config).receive_deployment
end

Instance Method Details

#deploy!(deployment) ⇒ Boolean

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.

Parameters:

  • deployment (Hash) —

    the deployment payload. Recognized keys include :result, :from_revision, :to_revision, :environment, :branch and :servers.

Returns:

  • (Boolean) —

    true when Redmine created the deployment, false otherwise.



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/capistrano/redmine/deployment/client.rb', line 109

def deploy!(deployment)
  log_deploy(deployment) if log?

  response = send_deployment(deployment)

  if response['deployment']
    log_deploy_done(response) if log?

    true
  else
    log_deploy_errors(response) if log?

    false
  end
end

#log? ⇒ Boolean

Returns whether console logging is currently enabled.

Returns:

  • (Boolean) —

    whether console logging is currently enabled.



94
95
96
 
# File 'lib/capistrano/redmine/deployment/client.rb', line 94

def log?
  @logging
end

#receive_deployment ⇒ Hash, ...

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.

Returns:

  • (Hash) —

    the single deployment entry when one exists.

  • (nil) —

    when the endpoint is reachable but has no entries yet.

  • (false) —

    when the request itself failed (non-2xx / errors).



135
136
137
138
139
140
141
142
 
# File 'lib/capistrano/redmine/deployment/client.rb', line 135

def receive_deployment
  response = fetch_deployments

  return false unless response.is_a?(Hash)
  return false if response['errors']

  extract_deployment(response)
end

#silent! ⇒ false

Disables console logging for this client.

Returns:

  • (false) 


89
90
91
 
# File 'lib/capistrano/redmine/deployment/client.rb', line 89

def silent!
  @logging = false
end