Merge "Define maven + docker verify, merge and stage jobs"
[releng/global-jjb.git] / docs / jjb / lf-maven-jobs.rst
index 3a2a088..1a0dc1e 100644 (file)
@@ -27,6 +27,20 @@ Runs Sonar against a Maven project.
     :mvn-version: Version of Maven to execute Sonar with.
     :mvn-settings: Maven settings.xml file containing credentials to use.
 
+lf-infra-maven-sonarcloud
+-------------------------
+
+Runs Sonar against a Maven project and pushes results to SonarCloud.
+
+:Required Parameters:
+
+    :java-version: Version of Java to execute Sonar with.
+    :mvn-version: Version of Maven to execute Sonar with.
+    :mvn-settings: Maven settings.xml file containing credentials to use.
+    :sonarcloud-project-key: SonarCloud project key.
+    :sonarcloud-project-organization: SonarCloud project organization.
+    :sonarcloud-api-token: SonarCloud API Token.
+
 lf-maven-build
 --------------
 
@@ -47,11 +61,29 @@ lf-maven-deploy
 
 Calls the maven deploy script to push artifacts to Nexus.
 
+lf-maven-versions-plugin
+------------------------
+
+Conditionally calls Maven versions plugin to set, update and commit the maven `versions:set`.
+
+:Required Parameters:
+
+    :maven-versions-plugin: Whether to call Maven versions plugin or not. (default: false)
+    :mvn-version: Version of Maven to execute Sonar with.
+    :mvn-pom: Location of pom.xml.
+    :mvn-settings: Maven settings.xml file containing credentials to use.
+
 lf-maven-stage
----------------
+--------------
 
 Calls the maven stage script to push artifacts to a Nexus staging repository.
 
+:Required Parameters:
+
+    :mvn-global-settings: The name of the Maven global settings to use for
+        Maven configuration.
+    :mvn-settings: The name of settings file containing credentials for the project.
+
 lf-update-java-alternatives
 ---------------------------
 
@@ -92,9 +124,6 @@ Produces a CLM scan of the code into Nexus IQ Server.
     :build-timeout: Timeout in minutes before aborting build. (default: 60)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
     :java-version: Version of Java to use for the build. (default: openjdk8)
-    :mvn-central: Set to 'true' to also stage to OSSRH. This is for projects
-        that want to release to Maven Central. If set the parameter
-        ``ossrh-profile-id`` also needs to be set. (default: false)
     :mvn-global-settings: The name of the Maven global settings to use for
         Maven configuration. (default: global-settings)
     :mvn-opts: Sets MAVEN_OPTS. (default: '')
@@ -106,8 +135,6 @@ Produces a CLM scan of the code into Nexus IQ Server.
         For example 'odl-'. (default: '')
     :nexus-iq-stage: Stage the policy evaluation will be run against on
         the Nexus IQ Server. (default: 'build')
-    :ossrh-profile-id: Profile ID for project as provided by OSSRH.
-        (default: '')
     :stream: Keyword that can be used to represent a release code-name.
         Often the same as the branch. (default: master)
     :submodule-recursive: Whether to checkout submodules recursively.
@@ -126,7 +153,7 @@ Expects javadocs to be available in $WORKSPACE/target/site/apidocs
 
 :Template Names:
 
-    - {project-name}-maven-javadoc-publish-{stream}
+    - {project-name}-maven-javadoc-publish-{stream}-{java-version}
     - gerrit-maven-javadoc-publish
     - github-maven-javadoc-publish
 
@@ -172,7 +199,7 @@ Expects javadocs to be available in $WORKSPACE/target/site/apidocs
 
 :Template Names:
 
-    - {project-name}-maven-javadoc-verify-{stream}
+    - {project-name}-maven-javadoc-verify-{stream}-{java-version}
     - gerrit-maven-javadoc-verify
     - github-maven-javadoc-verify
 
@@ -265,11 +292,37 @@ This job uses the following strategy to deploy jobs to Nexus:
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)
-
     :gerrit_merge_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths which can be used to
         filter which file modifications will trigger a build.
 
+Maven Merge for Docker
+----------------------
+
+Produces a snapshot docker image in a Nexus registry. Appropriate for
+Java projects that do not need to deploy any POM or JAR files.
+
+Similar to Maven Merge as described above but logs in to Docker
+registries first and skips the lf-maven-deploy builder. The project
+POM file should invoke a plugin to build and push a Docker image. The
+base image should be pulled from the registry in the environment
+variable CONTAINER_PULL_REGISTRY. The new image should be pushed to the
+registry in the environment variable CONTAINER_PUSH_REGISTRY.
+
+:Template Names:
+
+    - {project-name}-maven-docker-merge-{stream}
+    - gerrit-maven-docker-merge
+    - github-maven-docker-merge
+
+:Required parameters:
+
+    :container-public-registry: Docker registry source with base images.
+    :container-snapshot-registry: Docker registry target for the deploy action.
+
+All other required and optional parameters are identical to the Maven Merge job
+described above.
+
 Maven Stage
 -----------
 
@@ -309,11 +362,17 @@ directory is then used later to deploy to Nexus.
     :deploy-path:    The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
     :java-version: Version of Java to use for the build. (default: openjdk8)
+    :mvn-central: Set to 'true' to also stage to OSSRH. This is for projects
+        that want to release to Maven Central. If set the parameter
+        ``ossrh-profile-id`` also needs to be set. (default: false)
+    :maven-versions-plugin: Whether to call Maven versions plugin or not. (default: false)
     :mvn-global-settings: The name of the Maven global settings to use for
         Maven configuration. (default: global-settings)
     :mvn-opts: Sets MAVEN_OPTS. (default: '')
     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
     :mvn-version: Version of maven to use. (default: mvn35)
+    :ossrh-profile-id: Profile ID for project as provided by OSSRH.
+        (default: '')
     :sign-artifacts: Sign artifacts with Sigul. (default: false)
     :stream: Keyword that can be used to represent a release code-name.
         Often the same as the branch. (default: master)
@@ -324,6 +383,36 @@ directory is then used later to deploy to Nexus.
 
     :gerrit_release_triggers: Override Gerrit Triggers.
 
+Maven Stage for Docker
+----------------------
+
+Produces a release candidate docker image in a Nexus registry.
+Appropriate for Java projects that do not need to deploy any POM or
+JAR files.
+
+Similar to Maven Stage as described above but logs in to Docker
+registries first and skips the lf-maven-deploy builder. The project
+POM file should invoke a plugin to build and push a Docker image. The
+base image should be pulled from the registry in the environment
+variable CONTAINER_PULL_REGISTRY. The new image should be pushed to the
+registry in the environment variable CONTAINER_PUSH_REGISTRY.
+
+:Template Names:
+
+    - {project-name}-maven-docker-stage-{stream}
+    - gerrit-maven-docker-stage
+    - github-maven-docker-stage
+
+:Required parameters:
+
+    :container-public-registry: Docker registry source with base images.
+    :container-staging-registry: Docker registry target for the deploy action.
+
+All other required and optional parameters are identical to the Maven Stage job
+described above.
+
+.. _maven-sonar:
+
 Maven Sonar
 -----------
 
@@ -363,6 +452,14 @@ interest in that kind of support.
     :mvn-opts: Sets MAVEN_OPTS. (default: '')
     :mvn-params: Additional mvn parameters to pass to the cli. (default: '')
     :mvn-version: Version of maven to use. (default: mvn35)
+    :sonar-mvn-goals: Maven goals to run for sonar analysis.
+        (default: sonar:sonar)
+    :sonarcloud: Whether or not to use SonarCloud ``true|false``.
+        (default: false)
+    :sonarcloud-project-key: SonarCloud project key. (default: '')
+    :sonarcloud-project-organization: SonarCloud project organization.
+        (default: '')
+    :sonarcloud-api-token: SonarCloud API Token. (default: '')
     :stream: Keyword that can be used to represent a release code-name.
         Often the same as the branch. (default: master)
     :submodule-recursive: Whether to checkout submodules recursively.
@@ -372,6 +469,12 @@ interest in that kind of support.
 
     :gerrit_sonar_triggers: Override Gerrit Triggers.
 
+
+SonarCloud Example:
+
+.. literalinclude:: ../../.jjb-test/lf-maven-jobs/maven-sonarcloud.yaml
+   :language: yaml
+
 Maven Verify
 ------------
 
@@ -415,7 +518,28 @@ Verify job which runs mvn clean install to test a project build..
     :gerrit_trigger_file_paths: Override file paths which can be used to
         filter which file modifications will trigger a build.
 
-Maven Verify /w Dependencies
+Maven Verify for Docker
+-----------------------
+
+Similar to Maven Verify as described above but logs in to Docker
+registries first. The project POM file should invoke a plugin to build
+a Docker image. The base image should be pulled from the registry in
+the environment variable CONTAINER_PULL_REGISTRY.
+
+:Template Names:
+
+    - {project-name}-maven-docker-verify-{stream}-{mvn-version}-{java-version}
+    - gerrit-maven-docker-verify
+    - github-maven-docker-verify
+
+:Required parameters:
+
+    :container-public-registry: Docker registry source with base images.
+
+All other required and optional parameters are identical to the Maven Verify job
+described above.
+
+Maven Verify w/ Dependencies
 ----------------------------
 
 Verify job which runs mvn clean install to test a project build /w deps
@@ -429,7 +553,7 @@ via comment trigger.
     - {project-name}-maven-verify-deps-{stream}-{mvn-version}-{java-version}
     - gerrit-maven-verify-dependencies
 
-:Comment Trigger: recheck: SPACE_SEPERATED_LIST_OF_PATCHES
+:Comment Trigger: recheck: SPACE_SEPARATED_LIST_OF_PATCHES
 
 :Required parameters: