anchor.diff:  """
   }
   ----
  -
  -[source,syntaxhighlighter-pre]
  -----
  -...
  +or using `withEnv`
  +[source,groovy]
  +----
   withEnv(['JENKINS_MAVEN_AGENT_DISABLED=true']) {
      sh "mvn package"
   }
   ----
   
  -* Adding the system property
  -"[.code]``-Dorg.jenkinsci.plugins.pipeline.maven.eventspy.JenkinsMavenEventSpy.disabled=true``"
  -to the invocation of the mvn build
  -
  -== Why do I see messages "``+[WARNING] Picked up JAVA_TOOL_OPTIONS...+``" in the build logs?
  -
  -The Jenkins Pipeline Maven Plugin uses the "[.code]``JAVA_TOOL_OPTIONS``"
  -environment variable to pass options to subsequent Maven builds such as
  -the actual release build when invoking
  -"[.code]``mvn release:prepare release:perform``". The plugins passes the
  -properties "[.code]``-Dmaven.ext.class.path``" and
  -"[.code]``-Dorg.jenkinsci.plugins.pipeline.maven.reportsFolder``".
  -
  -When using the "[.code]``JAVA_TOOL_OPTIONS``", the JVM outputs a message during
  -its initialization.
  +* Adding the system property `-Dorg.jenkinsci.plugins.pipeline.maven.eventspy.JenkinsMavenEventSpy.disabled=true` to the invocation of the mvn build
  +
  +== Why do I see messages `[WARNING] Picked up JAVA_TOOL_OPTIONS...` in the build logs?
  +
  +The Jenkins Pipeline Maven Plugin uses the `JAVA_TOOL_OPTIONS` environment variable to pass options to subsequent Maven builds such as the actual release build when invoking `mvn release:prepare release:perform`.
  +The plugin passes the properties `-Dmaven.ext.class.path` and `-Dorg.jenkinsci.plugins.pipeline.maven.reportsFolder`.
  +
  +When using the `JAVA_TOOL_OPTIONS`, the JVM outputs a message during its initialization.
   
   With the Jenkins Pipeline Maven Plugin, this message looks like:
   
  +----
    [WARNING] Picked up JAVA_TOOL_OPTIONS: -Dmaven.ext.class.path="/path/to/workspace/...@tmp/withMaven.../pipeline-maven-spy.jar" -Dorg.jenkinsci.plugins.pipeline.maven.reportsFolder="/path/to/workspace/...@tmp"
  +----
   
   NOTE: It is not possible to disable this warning message.
   
  -== My downstream pipelines don't get triggered even if I use "Build whenever a SNAPSHOT dependency is built"
  -
  -A common reason why downstream pipelines don't get triggered when using
  -"Build whenever a SNAPSHOT dependency is built" is that the upstream
  -pipeline is using "mvn install" when the Jenkins Pipeline Maven
  -integration is configured to trigger pipelines on "mvn deploy".
  -
  -To configure the Jenkins Pipeline Maven integration to trigger
  -downstream pipelines on "mvn install":
  +== My downstream pipelines don't get triggered even if I use "Build whenever a SNAPSHOT dependency is built"!
  +
  +A common reason why downstream pipelines don't get triggered when using "Build whenever a SNAPSHOT dependency is built" is that the upstream pipeline is using "mvn install" when the Jenkins Pipeline Maven integration is configured to trigger pipelines on "mvn deploy".
  +
  +To configure the Jenkins Pipeline Maven integration to trigger downstream pipelines on "mvn install":
   
   * Either change the default configuration:
  - ** Navigate to "Manage Jenkins / Global Tools Configuration"
  - ** Click on "Add Publisher" and select "Pipeline Graph Publisher"
  - ** In the section "Downstream Pipeline Triggers", change the the
  -"Maven lifecycle threshold" from "deploy" to "install"
  -
  -image:https://wiki.jenkins.io/download/attachments/99451377/pipeline-graph-publisher-maven-lifecycle.png?version=3&modificationDate=1558992519000&api=v2[]
  +** Navigate to "Manage Jenkins / Global Tools Configuration"
  +** Click on "Add Publisher" and select "Pipeline Graph Publisher"
  +** In the section "Downstream Pipeline Triggers", change the "Maven lifecycle threshold" from "deploy" to "install"
  +
  +image:docs/images/pipeline-graph-publisher-maven-lifecycle.png[]
   
   * Or in the script of the upstream pipeline, configure
  -"``+withMaven(options: [pipelineGraphPublisher(lifecycleThreshold: 'install')]) {...}+``"
  -
  -== How can I troubleshoot problems of trigger of downstream pipelines
  -
  -* The Pipeline Maven Plugin uses the Jenkins log levels (see
  -https://wiki.jenkins.io/display/JENKINS/Logging#Logging-LogsinJenkins[here])
  -to output additional troubleshooting information in the pipeline
  -build logs (the "Console Output" menu of the build)
  -* To output additional troubleshooting information about the  trigger
  -of downstream pipelines, enable in "Manage Jenkins / System Log"
  -(docs
  -https://wiki.jenkins.io/display/JENKINS/Logging#Logging-LogsinJenkins[here])
  -the following loggers at a level FINE or FINER or more:
  - ** org.jenkinsci.plugins.pipeline.maven.publishers.PipelineGraphPublisher
  - ** org.jenkinsci.plugins.pipeline.maven.listeners.DownstreamPipelineTriggerRunListener
  -* Re run the pipeline that is supposed to trigger downstream
  -pipelines.
  -* Look at the pipeline build logs ("Console Output" menu), ensure that
  -the build is completed and that the following message is displayed
  -in the logs: "[withMaven] downstreamPipelineTriggerRunListener -
  -completed in XXX ms". Troubleshooting details are added
  -
  -== How do I capture the log file generated by the Jenkins Maven Event Spy
  -
  -You can archive the XML log file generated by the Jenkins Maven Event
  -Spy creating the marker file ".archive-jenkins-maven-event-spy-logs".
  -
  -Sample:
  -
  -[source,syntaxhighlighter-pre]
  +
  +[source,groovy]
  +----
  +withMaven(options: [pipelineGraphPublisher(lifecycleThreshold: 'install')]) {
  +/* sh/bat ...*/
  +}
  +----
  +
  +== How can I troubleshoot problems of trigger of downstream pipelines?
  +
  +* The Pipeline Maven Plugin uses the Jenkins log levels (see https://www.jenkins.io/doc/book/system-administration/viewing-logs/#logs-in-jenkins[here]) to output additional troubleshooting information in the pipeline build logs (the "Console Output" menu of the build).
  +* To output additional troubleshooting information about the  trigger of downstream pipelines, enable in "Manage Jenkins / System Log" (docs https://www.jenkins.io/doc/book/system-administration/viewing-logs/#logs-in-jenkins[here]) the following loggers at a level FINE or FINER or more:
  +** `org.jenkinsci.plugins.pipeline.maven.publishers.PipelineGraphPublisher`
  +** `org.jenkinsci.plugins.pipeline.maven.listeners.DownstreamPipelineTriggerRunListener`
  +* Re run the pipeline that is supposed to trigger downstream pipelines.
  +* Look at the pipeline build logs ("Console Output" menu), ensure that the build is completed and that the following message is displayed in the logs:
  +----
  +[withMaven] downstreamPipelineTriggerRunListener - completed in XXX ms
  +----
  +Troubleshooting details are added
  +
  +== How do I capture the log file generated by the Jenkins Maven Event Spy?
  +
  +You can archive the XML log file generated by the Jenkins Maven Event Spy creating the marker file `.archive-jenkins-maven-event-spy-logs`.
  +
  +.Sample
  +[source,groovy]
   ----
   withMaven() {
       sh "mvn package"
  
positive.code: 
  == How can I reduce the footprint of the database of the Jenkins Pipeline Maven Plugin?
  
  The Jenkins pipeline Maven plugin uses a database to trigger downstream
  pipelines when a snapshot is built.
  
  For production grade deployments, a MySQL database is needed instead of
  the embedded H2 database. My SQL 5.6+, Amazon Aurora MySQL and MariaDB
  10.2+ have been successfully tested.
  
  To reduce the usage of the database, disable the "Pipeline Graph
  Publisher" navigating to "Manage Jenkins / Global Tool Configuration /
  Pipeline Maven Configuration" then clicking on "Add Publisher Options",
  selecting "Pipeline Graph Publisher" and checking the "disabled"
  checkbox.
  
  image:https://wiki.jenkins.io/download/attachments/99451377/pipeline-maven-plugin-configuration-disabled-pipeline-graph-publisher.png?version=1&modificationDate=1546457421000&api=v2[]
  
  == Why do I see messages "[withMaven] One or multiple Maven executions have been ignored..." in the build logs?
  
  The message "[withMaven] One or multiple Maven executions have been
  ignored by the Jenkins Pipeline Maven Plugin because they have been
  interrupted before completion..." because one or several Maven execution
  (e.g. "[.code]``mvn deploy``") have been interrupted before they could gracefully
  complete.
  
  The event "[.code]``org.apache.maven.eventspy.EventSpy#close()``" has not been
  invoked on the Maven event spies.
  
  This interruption usually happens because the mvn process has been
  killed by the Operating System, typically for memory constraints in
  Docker or cgroups environments. Another cause is a "[.code]``kill -9``" during
  the build.
  
  == Why do I see messages "javax.xml.parsers.FactoryConfigurationError: Provider for class javax.xml.parsers.DocumentBuilderFactory cannot be created"
  
  This error is caused by the installation of another plugin that pulls an
  outdated version of Apache Xerces. That pulls a version of Apache Xerces
  that is not compatible with the version of the JVM. Typically, Xerces
  2.6 will not be compatible with a JDK 8 due to changes in the JAXP API
  (sample: https://issues.jenkins-ci.org/browse/JENKINS-47486[JENKINS-47486] -
  Getting issue details... STATUS ).
  
  The solution is to get this plugin updated so that it uses a more recent
  of Xerces that would be compatible with the JDK.
  
  To identify the plugin that is pulling an outdated version of a JAXP
  implementation (typically Xerces), navigate to the Jenkins Script
  Console ("Manage Jenkins" then "Script Console") and execute the
  following groovy script:
  
  [source,syntaxhighlighter-pre]
  ----
  String className = "org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"
  
  
negative.code: [[pipeline-maven-plugin-faq]]
  = Pipeline Maven Plugin FAQ
  :toc: macro
  :toc-title:
  ifdef::env-github[]
  :tip-caption: :bulb:
  :note-caption: :information_source:
  :important-caption: :heavy_exclamation_mark:
  :caution-caption: :fire:
  :warning-caption: :warning:
  endif::[]
  
  Frequently Asked Questions about the Pipeline Maven Plugin
  
  toc::[]
  
  == How to use the Pipeline Maven Plugin with Docker?
  
  NOTE: Since version 3.0.3
  
  Since the version 1.14 of the Docker Pipeline plugin, `withMaven` requires to
  
  * Either prepend the `MVN_CMD_DIR` environment variable to the `PATH` environment variable in every `sh` step that invokes `mvn` (e.g. `sh 'export PATH=$MVN_CMD_DIR:$PATH && mvn clean deploy`).
  * Or use Takari's Maven Wrapper (e.g. `sh './mvnw clean deploy'`)
  
  If omitted, the Maven settings file and Mven global settings file will not be injected in the Maven execution.
  
  === Using `withMaven` with `docker.image(...).inside{...}` and a Jenkins Scripted Pipeline
  
  **Prepending MVN_CMD_DIR to PATH**
  
  [source,groovy]
  ----
  node("linux-agent-running-docker") { // Linux agent with the Docker daemon
      docker.image('maven').inside { // Docker image with Maven installed
          withMaven() {
              git "https://github.com/cyrille-leclerc/my-jar.git"
              sh "export PATH=$MVN_CMD_DIR:$PATH && mvn clean deploy" // 'mvn' command: need to add the $MVN_CMD_DIR to $PATH
          }
  