Allow update to provide plugin_info via yaml

Getting plugin info requires Administrator permissions. It seems the
test command allows providing the plugin_info details via a yaml
configuration file. This patch allows the same command to be passed to
the update command to allow us to configure the plugin versions manually
and not require administrator permissions.

Additionally this patch adds a new command called get-plugins-info
which can create the plugins_info.yaml file to pass to the
plugin_info_path.

See:
http://lists.openstack.org/pipermail/openstack-infra/2016-June/004388.html

Change-Id: I5a34979407d863a84f34afbf8f565081ec52190a
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

2 files changed, 31 insertions, 0 deletions

diff --git a/doc/source/execution.rst b/doc/source/execution.rst
index 43a85937..1006e818 100644
--- a/doc/source/execution.rst
+++ b/doc/source/execution.rst
@@ -313,6 +313,22 @@ To delete jobs/views that only have 'foo' in their name::
 
   jenkins-jobs delete --path ./myjobs \*foo\*
 
+Providing Plugins Info
+^^^^^^^^^^^^^^^^^^^^^^
+With Jenkins LTS 1.651.1+ retrieving plugins info became a secure feature and
+now requires Administrator rights to use [#f2]. This causes JJB to no longer be
+able to work in situations where a user wants to publish jobs to Jenkins but is
+not able to receive the Administrator permissions. In this case we can provide
+a plugins_info.yaml file containing the plugin versions data needed by JJB to
+parse the job templates.
+
+To generate a plugins info, using an account with Administrator rights:
+
+  jenkins-jobs get-plugins-info -o plugins_info.yaml
+
+To run JJB update using the plugins_info.yaml:
+
+  jenkins-jobs update -p plugins_info.yaml ./myjobs
 
 .. _command-reference:
 
@@ -323,8 +339,11 @@ Command Reference
 .. program-output:: jenkins-jobs update --help
 .. program-output:: jenkins-jobs delete-all --help
 .. program-output:: jenkins-jobs delete --help
+.. program-output:: jenkins-jobs get-plugins-info --help
 
 .. rubric:: Footnotes
 .. [#f1] The cache default location is at ``~/.cache/jenkins_jobs``, which
          can be overridden by setting the ``XDG_CACHE_HOME`` environment
          variable.
+.. [#f2] Jenkins Security Advisory affecting plugins info retrieval
+         https://wiki.jenkins-ci.org/display/SECURITY/Jenkins+Security+Advisory+2016-05-11
diff --git a/doc/source/quick-start.rst b/doc/source/quick-start.rst
index 6b1edba4..64a3c38f 100644
--- a/doc/source/quick-start.rst
+++ b/doc/source/quick-start.rst
@@ -80,6 +80,18 @@ To delete a job::
 
 The above command deletes the job `simple` from the Jenkins master.
 
+.. _use-case-5:
+
+Use Case 5: Providing plugins info
+----------------------------------
+
+To generate a plugins info, using an account with Administrator rights:
+
+    jenkins-jobs get-plugins-info -o plugins_info.yaml
+
+To run JJB update using the plugins_info.yaml:
+
+    jenkins-jobs update -p plugins_info.yaml ./myjobs
 
 
 Please refer to the jenkins-jobs :ref:`command-reference` and the