search

jenkinsci / plugin-installation-manager-tool

Plugin Manager CLI tool for Jenkins
MIT License
395 stars 202 forks source link
cli hacktoberfest jenkins plugin-manager

readme

Plugin Installation Manager Tool for Jenkins

GitHub release (latest SemVer) Downloads Join the chat at https://gitter.im/jenkinsci/plugin-installation-manager-cli-tool

The plugin manager downloads plugins and their dependencies into a folder so that they can be easily imported into an instance of Jenkins. The goal of this tool is to replace the Docker install-plugins.sh script and the many other implementations of plugin management that have been recreated across Jenkins. The tool also allows users to see more information about the plugins they are downloading, such as available updates and security warnings. By default, plugins will be downloaded; the user can specify not to download plugins using the --no-download option.

Usage

Getting Started

Download the latest jenkins-plugin-manager jar from here and run it as shown below.

java -jar jenkins-plugin-manager-*.jar --war /your/path/to/jenkins.war --plugin-download-directory /your/path/to/plugins/ --plugin-file /your/path/to/plugins.txt --plugins delivery-pipeline-plugin:1.3.2 deployit-plugin

Alternatively, build and run the plugin manager yourself from source:

mvn clean install 
java -jar plugin-management-cli/target/jenkins-plugin-manager-*.jar --war /file/path/jenkins.war --plugin-download-directory /your/path/to/plugins/ --plugin-file /file/path/plugins.txt --plugins delivery-pipeline-plugin:1.3.2 deployit-plugin

If you use a Jenkins docker image the plugin manager can be invoked inside the running container via the bundled jenkins-plugin-cli shell script:

docker cp /your/path/to/plugins.txt <container_name>:/tmp/plugins.txt
docker exec -it <container_name> /bin/bash
jenkins-plugin-cli --plugin-file /tmp/plugins.txt --plugins delivery-pipeline-plugin:1.3.2 deployit-plugin
cp -r -p /usr/share/jenkins/ref/plugins/. /var/jenkins_home/plugins/.
exit

CLI Options

Advanced configuration

Plugin Input Format

The expected format for plugins in the .txt file or entered through the --plugins CLI option is artifact ID:version or artifact ID:url or artifact:version:url

Use plugin artifact ID, without -plugin extension. If a plugin cannot be downloaded, -plugin will be appended to the name and download will be retried. This is for cases in which plugins don't follow the rules about artifact ID (i.e. docker plugin).

The version and download url are optional. By default, the latest version of the plugin will be downloaded. If both a version and a url are supplied, the version will not be used to determine the plugin download location and the library will attempt to download the plugin from the given url.

The following custom version specifiers can also be used:

A set of plugins can also be provided through a YAML file, using the following format:

plugins:
  - artifactId: git
    source:
      version: latest
  - artifactId: job-import-plugin
    source:
      version: 2.1
  - artifactId: docker
  - artifactId: cloudbees-bitbucket-branch-source
    source:
      version: 2.4.4
  - artifactId: script-security
    source:
      url: http://ftp-chi.osuosl.org/pub/jenkins/plugins/script-security/1.56/script-security.hpi
  - artifactId: workflow-step-api
    groupId: org.jenkins-ci.plugins.workflow
    source:
      version: 2.19-rc289.d09828a05a74
  ...

As with the plugins.txt file, version and URL are optional. If no version is provided, the latest version is used by default. If a groupId is provided, the tool will try to download the plugin from the Jenkins incrementals repository.

Updating plugins

The CLI can output a new file with a list of updated plugin references.

Text format:

$ java -jar jenkins-plugin-manager-*.jar --available-updates --output txt --plugins mailer:1.31

Result:

mailer:1.32

YAML format:

$ java -jar jenkins-plugin-manager-*.jar --available-updates --output yaml --plugins mailer:1.31

Result:

plugins:
- artifactId: "mailer"
  source:
    version: "1.32"

Human readable:

$ java -jar jenkins-plugin-manager-*.jar --available-updates --plugins mailer:1.31

Result:

Available updates:
mailer (1.31) has an available update: 1.32

Examples

If a URL is included, then a placeholder should be included for the version. Examples of plugin inputs:

If a plugin to be downloaded from the incrementals repository is requested using the -plugins option from the CLI, the plugin name should be enclosed in quotes, since the semi-colon is otherwise interpreted as the end of the command.

java -jar jenkins-plugin-manager-*.jar -p "workflow-support:incrementals;org.jenkins-ci.plugins.workflow;2.19-rc289.d09828a05a74"

Proxy Support

Proxy support is available using standard Java networking system properties http.proxyHost and http.proxyPort. Note that this provides only basic NTLM support and you may need to use an authentication proxy like CNTLM to cover more advanced authentication use cases.

# Example using proxy system properties
java -Dhttp.proxyPort=3128 -Dhttp.proxyHost=myproxy.example.com -Dhttps.proxyPort=3128 -Dhttps.proxyHost=myproxy.example.com -jar jenkins-plugin-manager-*.jar

Other Information

The plugin manager tries to use update center data to get the latest information about a plugin's dependencies. If this information is unavailable, it will use the dependency information from the downloaded plugin's MANIFEST.MF file. By default, the versions of the plugin dependencies are determined by the update center metadata or the plugin MANIFEST.MF file, but the user can specify other behavior using the latest or latest-specified options.

For plugins listed in a .txt file, each plugin must be listed on a new line. Comments beginning with # will be filtered out.

Support for downloading plugins from maven is not currently supported. JENKINS-58217

When using --latest you may run into a scenario where the jenkins update mirror contains the directory of the newer version of a plugin(release in progress), regardless of if there is a jpi to download, which results in a download failure. It's recommended that you pin your plugin requirement versions until the mirror has been updated to more accurately represent what is available. More information on this challenge can be found here, and here.

The version-pinning behavior of this plugin installer has changed compared to the previous Jenkins plugin installer. By default, --latest option defaults to true, which means that even if you pass a list of pinned versions, these may fail to be installed correctly if they or some other dependency has a newer latest version available. In order to use only pinned versions of plugins, you must pass --latest=false. NOTE: When a new dependency is added to a plugin, it won’t get updated until you notice that it’s missing from your plugin list. (Details here: https://github.com/jenkinsci/plugin-installation-manager-tool/issues/250)

Contributions

Thanks to all our contributors! Check out our CONTRIBUTING file to learn how to get started with issues.