jenkins_plugin - Add or remove Jenkins plugin¶

New in version 2.2.

Synopsis
Parameters
Notes
Examples
Return Values
Status
Maintenance
- Author

Synopsis ¶

Ansible module which helps to manage Jenkins plugins.

Parameters ¶

Parameter	Choices/Defaults	Comments
client_cert		PEM formatted certificate chain file to be used for SSL client authentication. This file can also include the key as well, and if the key is included, `client_key` is not required.
client_key		PEM formatted file that contains your private key to be used for SSL client authentication. If `client_cert` contains both the certificate and key, this option is not required.
force bool	Choices: no ← yes	If `yes` do not get a cached copy. aliases: thirsty
force_basic_auth bool	Choices: no ← yes	Credentials specified with url_username and url_password should be passed in HTTP Header.
group	Default: jenkins	Name of the Jenkins group on the OS.
http_agent	Default: ansible-httpget	Header to identify as, generally appears in web server logs.
jenkins_home	Default: /var/lib/jenkins	Home directory of the Jenkins user.
mode		File mode applied on versioned plugins.
name		Plugin name.
owner	Default: jenkins	Name of the Jenkins user on the OS.
state	Choices: absent present ← pinned unpinned enabled disabled latest	Desired plugin state. If the `latest` is set, the check for new version will be performed every time. This is suitable to keep the plugin up-to-date.
timeout	Default: 30	Server connection timeout in secs.
updates_expiration	Default: 86400	Number of seconds after which a new copy of the update-center.json file is downloaded. This is used to avoid the need to download the plugin to calculate its checksum when `latest` is specified. Set it to `0` if no cache file should be used. In that case, the plugin file will always be downloaded to calculate its checksum when `latest` is specified.
updates_url	Default: https://updates.jenkins-ci.org	URL of the Update Centre. Used as the base URL to download the plugins and the update-center.json JSON file.
url	Default: http://localhost:8080	URL of the Jenkins server.
url_password		The password for use in HTTP basic authentication. If the url_username parameter is not specified, the url_password parameter will not be used.
url_username		The username for use in HTTP basic authentication. This parameter can be used without url_password for sites that allow empty passwords
use_proxy bool	Choices: no yes ←	If `no`, it will not use a proxy, even if one is defined in an environment variable on the target hosts.
validate_certs bool	Choices: no yes ←	If `no`, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.
version		Plugin version number. If this option is specified, all plugin dependencies must be installed manually. It might take longer to verify that the correct version is installed. This is especially true if a specific version number is specified. Quote the version to prevent the value to be interpreted as float. For example if `1.20` would be unquoted, it would become `1.2`.
with_dependencies bool	Choices: no yes ←	Defines whether to install plugin dependencies. This option takes effect only if the version is not defined.

Notes ¶

Note

Plugin installation should be run under root or the same user which owns the plugin files on the disk. Only if the plugin is not installed yet and no version is specified, the API installation is performed which requires only the Web UI credentials.
It’s necessary to notify the handler or call the service module to restart the Jenkins service after a new plugin was installed.
Pinning works only if the plugin is installed and Jenkis service was successfully restarted after the plugin installation.
It is not possible to run the module remotely by changing the url parameter to point to the Jenkins server. The module must be used on the host where Jenkins runs as it needs direct access to the plugin files.
The params option was removed in Ansible 2.5 due to circumventing Ansible’s option handling

Examples ¶

- name: Install plugin
  jenkins_plugin:
    name: build-pipeline-plugin

- name: Install plugin without its dependencies
  jenkins_plugin:
    name: build-pipeline-plugin
    with_dependencies: no

- name: Make sure the plugin is always up-to-date
  jenkins_plugin:
    name: token-macro
    state: latest

- name: Install specific version of the plugin
  jenkins_plugin:
    name: token-macro
    version: "1.15"

- name: Pin the plugin
  jenkins_plugin:
    name: token-macro
    state: pinned

- name: Unpin the plugin
  jenkins_plugin:
    name: token-macro
    state: unpinned

- name: Enable the plugin
  jenkins_plugin:
    name: token-macro
    state: enabled

- name: Disable the plugin
  jenkins_plugin:
    name: token-macro
    state: disabled

- name: Uninstall plugin
  jenkins_plugin:
    name: build-pipeline-plugin
    state: absent

#
# Example of how to authenticate
#
- name: Install plugin
  jenkins_plugin:
    name: build-pipeline-plugin
    url_username: admin
    url_password: p4ssw0rd
    url: http://localhost:8888

#
# Example of a Play which handles Jenkins restarts during the state changes
#
- name: Jenkins Master play
  hosts: jenkins-master
  vars:
    my_jenkins_plugins:
      token-macro:
        enabled: yes
      build-pipeline-plugin:
        version: "1.4.9"
        pinned: no
        enabled: yes
  tasks:
    - name: Install plugins without a specific version
      jenkins_plugin:
        name: "{{ item.key }}"
      register: my_jenkins_plugin_unversioned
      when: >
        'version' not in item.value
      with_dict: "{{ my_jenkins_plugins }}"

    - name: Install plugins with a specific version
      jenkins_plugin:
        name: "{{ item.key }}"
        version: "{{ item.value['version'] }}"
      register: my_jenkins_plugin_versioned
      when: >
        'version' in item.value
      with_dict: "{{ my_jenkins_plugins }}"

    - name: Initiate the fact
      set_fact:
        jenkins_restart_required: no

    - name: Check if restart is required by any of the versioned plugins
      set_fact:
        jenkins_restart_required: yes
      when: item.changed
      with_items: "{{ my_jenkins_plugin_versioned.results }}"

    - name: Check if restart is required by any of the unversioned plugins
      set_fact:
        jenkins_restart_required: yes
      when: item.changed
      with_items: "{{ my_jenkins_plugin_unversioned.results }}"

    - name: Restart Jenkins if required
      service:
        name: jenkins
        state: restarted
      when: jenkins_restart_required

    - name: Wait for Jenkins to start up
      uri:
        url: http://localhost:8080
        status_code: 200
        timeout: 5
      register: jenkins_service_status
      # Keep trying for 5 mins in 5 sec intervals
      retries: 60
      delay: 5
      until: >
         'status' in jenkins_service_status and
         jenkins_service_status['status'] == 200
      when: jenkins_restart_required

    - name: Reset the fact
      set_fact:
        jenkins_restart_required: no
      when: jenkins_restart_required

    - name: Plugin pinning
      jenkins_plugin:
        name: "{{ item.key }}"
        state: "{{ 'pinned' if item.value['pinned'] else 'unpinned'}}"
      when: >
        'pinned' in item.value
      with_dict: "{{ my_jenkins_plugins }}"

    - name: Plugin enabling
      jenkins_plugin:
        name: "{{ item.key }}"
        state: "{{ 'enabled' if item.value['enabled'] else 'disabled'}}"
      when: >
        'enabled' in item.value
      with_dict: "{{ my_jenkins_plugins }}"

Return Values ¶

Common return values are documented here, the following are the fields unique to this module:

Key	Returned	Description
plugin string	success	plugin name Sample: build-pipeline-plugin
state string	success	state of the target, after execution Sample: present

Status ¶

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance ¶

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author ¶

Jiri Tyr (@jtyr)

Hint

If you notice any issues in this documentation you can edit this document to improve it.