jenkins_plugin – Add or remove Jenkins plugin
Synopsis
- Ansible module which helps to manage Jenkins plugins.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
client_cert
path
|
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
path
|
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
boolean
|
|
If
yes do not get a cached copy.
Alias
thirsty has been deprecated and will be removed in 2.13.
aliases: thirsty |
force_basic_auth
boolean
|
|
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
string
|
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
-
|
Default:
"0644"
|
File mode applied on versioned plugins.
|
name
- /
required
|
Plugin name.
|
|
owner
-
|
Default:
"jenkins"
|
Name of the Jenkins user on the OS.
|
state
-
|
|
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.io"
|
URL of the Update Centre.
Used as the base URL to download the plugins and the
update-center.json JSON file.
|
url
string
|
Default:
"http://localhost:8080"
|
URL of the Jenkins server.
|
url_password
string
|
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
string
|
The username for use in HTTP basic authentication.
This parameter can be used without
url_password for sites that allow empty passwords
|
|
use_proxy
boolean
|
|
If
no , it will not use a proxy, even if one is defined in an environment variable on the target hosts.
|
validate_certs
boolean
|
|
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
boolean
|
|
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 Jenkins 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 not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- Jiri Tyr (@jtyr)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/modules/jenkins_plugin_module.html