Class: JenkinsApi::Client::PluginManager

Inherits:
Object
  • Object
show all
Defined in:
lib/jenkins_api_client/plugin_manager.rb

Overview

This classes communicates with the /pluginManager API for listing installed plugins, installing new plgins through hacks, and performing a lot of operations on installed plugins. It also gives the ability to obtain the details about available plugins in Jenkins update center by communicating with /updateCenter API.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ PluginManager

Initializes a new PluginManager object.

Parameters:

  • client (Object) —

    a reference to Client



37
38
39
40
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 37

def initialize(client)
  @client = client
  @logger = @client.logger
end

Class Method Details

.plugin_action_method(action, post_endpoint) ⇒ Object

Defines a method to perform the given action on plugin(s)

Parameters:

  • action (Symbol) —

    the action to perform

  • post_endpoint (Symbol) —

    the endpoint in the POST request for the action



54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 54

def self.plugin_action_method(action, post_endpoint)
  define_method(action) do |plugins|
    plugins = [plugins] unless plugins.is_a?(Array)
    @logger.info "Performing '#{action}' on plugins: #{plugins.inspect}"
    plugins.each do |plugin|
      @client.api_post_request(
        "/pluginManager/plugin/#{plugin}/#{post_endpoint}"
      )
    end
  end
end

Instance Method Details

#check_for_updates ⇒ Object

Requests the Jenkins plugin manager to check for updates by connecting to the update site.

See Also:



438
439
440
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 438

def check_for_updates
  @client.api_post_request("/pluginManager/checkUpdates")
end

#disable(plugins) ⇒ Object

Disables the specified plugin or list of plugins. This method makes a POST request for every plugin specified - so it might lead to some delay if a big list is provided.

Parameters:

  • plugins (String, Array) —

    a single plugin or list of plugins to be uninstalled

See Also:



431
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 431

plugin_action_method :disable, :makeDisabled

#downgrade(plugins) ⇒ Object

Downgrades the specified plugin or list of plugins. This method makes s POST request for every plugin specified - so it might lead to some delay if a big list is provided.

Parameters:

  • a (String, Array) —

    single plugin or list of plugins to be downgraded

See Also:



384
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 384

plugin_action_method :downgrade, :downgrade

#enable(plugins) ⇒ Object

Enables the specified plugin or list of plugins. This method makes a POST request for every plugin specified - so it might lead to some delay if a big list is provided.

Parameters:

  • plugins (String, Array) —

    a single plugin or list of plugins to be uninstalled

See Also:



415
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 415

plugin_action_method :enable, :makeEnabled

#get_available_info(plugin) ⇒ Hash

Obtains the information about a plugin that is available in the Jenkins update center

Examples:

Obtaining the details of a plugin available in jenkins

>> @client.plugin.get_available_info "status-view"
=> {
     "name"=>"status-view",
     "sourceId"=>"default",
     "url"=>"https://updates.jenkins.io/download/plugins/status-view/1.0/status-view.hpi",
     "version"=>"1.0",
     "categories"=>["ui"],
     "compatibleSinceVersion"=>nil,
     "compatibleWithInstalledVersion"=>true,
     "dependencies"=>{},
     "excerpt"=>"View type to show jobs filtered by the status of the last completed build.",
     "installed"=>nil, "neededDependencies"=>[],
     "requiredCore"=>"1.342",
     "title"=>"Status View Plugin",
     "wiki"=>"https://wiki.jenkins.io/display/JENKINS/Status+View+Plugin"
   }

Parameters:

  • plugin (String) —

    the plugin ID to obtain information for

Returns:

  • (Hash) —

    the details of the given plugin



272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 272

def get_available_info(plugin)
  plugins = @client.api_get_request(
    "/updateCenter/coreSource",
    "depth=1"
  )["availables"]
  matched_plugin = plugins.select do |a_plugin|
    a_plugin["name"] == plugin
  end
  if matched_plugin.empty?
    raise Exceptions::PluginNotFound.new(
      @logger,
      "Plugin '#{plugin}' is not found"
    )
  else
    matched_plugin.first
  end
end

#get_installed_info(plugin) ⇒ Hash

Obtains the details of a single installed plugin

Examples:

Obtain the information of an installed plugin

>> @client.plugin.get_installed_info "ldap"
=> {
     "active"=>false,
     "backupVersion"=>"1.2",
     "bundled"=>true,
     "deleted"=>false,
     "dependencies"=>[],
     "downgradable"=>true,
     "enabled"=>false,
     "hasUpdate"=>false,
     "longName"=>"LDAP Plugin",
     "pinned"=>true,
     "shortName"=>"ldap",
     "supportsDynamicLoad"=>"MAYBE",
     "url"=>"https://wiki.jenkins.io/display/JENKINS/LDAP+Plugin",
     "version"=>"1.5"
   }

Parameters:

  • plugin (String) —

    the plugin ID of the desired plugin

Returns:

  • (Hash) —

    the details of the given installed plugin



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 155

def get_installed_info(plugin)
  @logger.info "Obtaining the details of plugin: #{plugin}"
  plugins = @client.api_get_request(
    "/pluginManager",
    "depth=1"
  )["plugins"]
  matched_plugin = plugins.select do |a_plugin|
    a_plugin["shortName"] == plugin
  end
  if matched_plugin.empty?
    raise Exceptions::PluginNotFound.new(
      @logger,
      "Plugin '#{plugin}' is not found"
    )
  else
    matched_plugin.first
  end
end

#install(plugins) ⇒ String Also known as: update

Installs a specific plugin or list of plugins. This method will install the latest available plugins that jenkins reports. The installation might not take place right away for some plugins and they might require restart of jenkins instances. This method makes a single POST request for the installation of multiple plugins. Updating plugins can be done the same way. When the install action is issued, it gets the latest version of the plugin if the plugin is outdated.

Examples:

Installing a plugin and restart jenkins if required

>> @client.plugin.install "s3"
=> "302" # Response code from plugin installation POST
>> @client.plugin.restart_required?
=> true # A restart is required for the installation completion
>> @client.system.restart(true)
=> "302" # A force restart is performed

Parameters:

  • plugins (String, Array) —

    a single plugin or a list of plugins to be installed

Returns:

  • (String) —

    the HTTP code from the plugin install POST request

See Also:



338
339
340
341
342
343
344
345
346
347
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 338

def install(plugins)
  # Convert the input argument to an array if it is not already an array
  plugins = [plugins] unless plugins.is_a?(Array)
  @logger.info "Installing plugins: #{plugins.inspect}"

  # Build the form data to post to jenkins
  form_data = {}
  plugins.each { |plugin| form_data["plugin.#{plugin}.default"] = "on" }
  @client.api_post_request("/pluginManager/install", form_data)
end

#list_available(filters = {}) ⇒ Hash<String, String>

List the available plugins from jenkins update center along with their version numbers

Examples:

Listing available plugins from jenkins

>> @client.plugin.list_available
=> {
     "accurev" => "0.6.18",
     "active-directory" => "1.33",
     "AdaptivePlugin" => "0.1",
     ...
     "zubhium" => "0.1.6"
   }

Listing available plugins matching a particular category

>> pp @client.plugin.list_available(:category => "ui")
=> {
     "all-changes"=>"1.3",
     "bruceschneier"=>"0.1",
     ...
     "xfpanel"=>"1.2.2"
   }

Listing available plugins matching a particular dependency

>> pp @client.plugin.list_available(:dependency => "git")
=> {
     "build-failure-analyzer"=>"1.5.0",
     "buildheroes"=>"0.2",
     ...
     "xpdev"=>"1.0"
   }

Parameters:

  • filters (Hash) (defaults to: {}) —

    optional filters to filter available plugins.

Options Hash (filters):

  • :category (Array) —

    the category of the plugin to filter

  • :dependency (Array) —

    the dependency of the plugin to filter

Returns:

  • (Hash<String, String>) —

    available plugins and their versions. returns an empty if no plugins are available.



215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 215

def list_available(filters = {})
  supported_filters = [:category, :dependency]
  filter_plural_map = {
    :dependency => "dependencies",
    :category => "categories"
  }
  unless filters.keys.all? { |filter| supported_filters.include?(filter) }
    raise ArgumentError, "Unsupported filters specified." +
      " Supported filters: #{supported_filters.inspect}"
  end
  # Compute the filters to be passed to the JSON tree parameter
  tree_filters =
    if filters.empty?
      ""
    else
      ",#{filters.keys.map{ |key| filter_plural_map[key] }.join(",")}"
    end

  availables = @client.api_get_request(
    "/updateCenter/coreSource",
    "tree=availables[name,version#{tree_filters}]"
  )["availables"]
  Hash[availables.map do |plugin|
    if filters.keys.all? do |key|
      !plugin[filter_plural_map[key]].nil? &&
        plugin[filter_plural_map[key]].include?(filters[key])
    end
      [plugin["name"], plugin["version"]]
    end
  end]
end

#list_installed(filters = {}) ⇒ Hash<String, String>

Obtains the list of installed plugins from Jenkins along with their version numbers with optional filters

Examples:

Listing installed plugins from jenkins

>> @client.plugin.list_installed
=> {
     "mailer" => "1.5",
     "external-monitor-job" => "1.1",
     "ldap" => "1.2"
   }
>> @client.plugin.list_installed(true)
=> {}

Listing installed plugins based on filters provided

>> @client.plugin.list_installed(
     :active => true, :deleted => false, :bundled => false
   )
=> {
     "sourcemonitor" => "0.2",
     "sms-notification" => "1.0",
     "jquery" => "1.7.2-1",
     "simple-theme-plugin" => "0.3",
     "jquery-ui" => "1.0.2",
     "analysis-core" => "1.49"
   }

Parameters:

  • filters (Hash) (defaults to: {}) —

    optional filters to apply. Use symbols for filter keys

Options Hash (filters):

  • :active (Boolean) —

    filter active/non-active plugins

  • :bundled (Boolean) —

    filter bundled/non-bundled plugins

  • :deleted (Boolean) —

    filter deleted/available plugins

  • :downgradable (Boolean) —

    filter downgradable plugins

  • :enabled (Boolean) —

    filter enabled/disabled plugins

  • :hasUpdate (Boolean) —

    filter plugins that has update available. Note that ‘U’ is capitalized in hasUpdate.

  • :pinned (Boolean) —

    filter pinned/un-pinned plugins

Returns:

  • (Hash<String, String>) —

    installed plugins and their versions matching the filter provided. returns an empty hash if there are no plugins matched the filters or no plugins are installed in jenkins.



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 108

def list_installed(filters = {})
  supported_filters = [
    :active, :bundled, :deleted, :downgradable, :enabled, :hasUpdate,
    :pinned
  ]
  unless filters.keys.all? { |filter| supported_filters.include?(filter) }
    raise ArgumentError, "Unsupported filters specified." +
      " Supported filters: #{supported_filters.inspect}"
  end
  tree_filters = filters.empty? ? "" : ",#{filters.keys.join(",")}"
  plugins = @client.api_get_request(
    "/pluginManager",
    "tree=plugins[shortName,version#{tree_filters}]"
  )["plugins"]
  installed = Hash[plugins.map do |plugin|
    if filters.keys.all? { |key| plugin[key.to_s] == filters[key] }
      [plugin["shortName"], plugin["version"]]
    end
  end.compact]
  installed
end

#list_updates ⇒ Hash<String, String>

List the available updates for plugins from jenkins update center along with their version numbers

Examples:

Listing available plugin updates from jenkins

>> @client.plugin.list_updates
=> {
     "ldap" => "1.5",
     "ssh-slaves" => "0.27",
     "subversion" => "1".50
   }

Returns:

  • (Hash<String, String>) —

    available plugin updates and their versions. returns an empty if no plugins are available.



304
305
306
307
308
309
310
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 304

def list_updates
  updates = @client.api_get_request(
    "/updateCenter/coreSource",
    "tree=updates[name,version]"
  )["updates"]
  Hash[updates.map { |plugin| [plugin["name"], plugin["version"]] }]
end

#restart_required? ⇒ Boolean

Whether restart required for the completion of plugin installations/uninstallations

Returns:

  • (Boolean) —

    whether restart is required for the completion for plugin installations/uninstallations.

See Also:



450
451
452
453
454
455
456
457
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 450

def restart_required?
  response = @client.api_get_request(
    "/updateCenter",
    "tree=restartRequiredForCompletion"
  )
  response["restartRequiredForCompletion"] ||
    !list_installed(:deleted => true).empty?
end

#to_s ⇒ Object

Returns a string representation of PluginManager class.



44
45
46
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 44

def to_s
  "#<JenkinsApi::Client::PluginManager>"
end

#uninstall(plugins) ⇒ Object

Uninstalls the specified plugin or list of plugins. Only the user installed plugins can be uninstalled. The plugins installed by default by jenkins (also known as bundled plugins) cannot be uninstalled. The call will succeed but the plugins wil still remain in jenkins installed. This method makes a POST request for every plugin requested - so it might lead to some delay if a big list is provided.

Parameters:

  • plugins (String, Array) —

    a single plugin or list of plugins to be uninstalled

See Also:



368
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 368

plugin_action_method :uninstall, :doUninstall

#unpin(plugins) ⇒ Object

Unpins the specified plugin or list of plugins. This method makes a POST request for every plugin specified - so it might lead to some delay if a big list is provided.

Parameters:

  • plugins (String, Array) —

    a single plugin or list of plugins to be uninstalled

See Also:



399
 
# File 'lib/jenkins_api_client/plugin_manager.rb', line 399

plugin_action_method :unpin, :unpin