Merge "Allow update to provide plugin_info via yaml"

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