Make gerrit-branch-lock work for all proj/branches

[releng/global-jjb.git] / docs / jjb / lf-ci-jobs.rst

diff --git a/docs/jjb/lf-ci-jobs.rst b/docs/jjb/lf-ci-jobs.rst
index 6184284..0fa7081 100644 (file)
--- a/docs/jjb/lf-ci-jobs.rst
+++ b/docs/jjb/lf-ci-jobs.rst
@@ -64,13 +64,6 @@ lf-infra-jjbini
 
 Provides jenkins_jobs.ini configuration for Jenkins.
 
 
 Provides jenkins_jobs.ini configuration for Jenkins.
 

-lf-infra-jjbini-sandbox
------------------------
-
-Provides jenkins_jobs.ini configuration for Jenkins sandbox.
-
-.. todo:: This needs to be consolidated into lf-infra-jjbini when JJB 2.0 is available
-

 lf-packer-common
 ----------------
 
 lf-packer-common
 ----------------
 


@@ -114,10 +107,13 @@ Job Templates
 Gerrit Branch Lock
 ------------------
 
 Gerrit Branch Lock
 ------------------
 

-Job submits a patch to lock or unlock a project's branch.
+Job submits a patch to lock or unlock a project's branch. This should only be
+loaded once, as "ci-management-gerrit-branch-lock" (or "ci-management"
+equivalent). That job will process lock/unlock requests for all projects and
+all branches.

 
 :Template Names:
 
 :Template Names:

-    - {project-name}-gerrit-branch-lock-{stream}
+    - {project-name}-gerrit-branch-lock

     - gerrit-branch-lock
 
 :Comment Trigger:
     - gerrit-branch-lock
 
 :Comment Trigger:


@@ -133,10 +129,7 @@ Job submits a patch to lock or unlock a project's branch.
 
 :Optional parameters:
 
 
 :Optional parameters:
 

-    :branch: Git branch to build against. (default: master)

     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)
     :git-url: URL to clone project from. (default: $GIT_URL/$GERRIT_PROJECT)

-    :stream: Keyword that can be used to represent a release code-name.
-        Often the same as the branch. (default: master)

     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)
     :gerrit_merge_triggers: Override Gerrit Triggers.
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)
     :gerrit_merge_triggers: Override Gerrit Triggers.


@@ -424,6 +417,8 @@ Runs `jenkins-jobs update` to update production job configuration
     :build-timeout: Timeout in minutes before aborting build. (default: 10)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)
     :build-timeout: Timeout in minutes before aborting build. (default: 10)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
     :jjb-cache: JJB cache location. (default: $HOME/.cache/jenkins_jobs)

+    :jjb-workers: Number of threads to run **update** with. Set to 0 by default
+        which is equivalent to the number of available CPU cores. (default: 0)

     :jjb-version: JJB version to install. (default: see job-template)
     :stream: Keyword that can be used to represent a release code-name.
         Often the same as the branch. (default: master)
     :jjb-version: JJB version to install. (default: see job-template)
     :stream: Keyword that can be used to represent a release code-name.
         Often the same as the branch. (default: master)


@@ -431,6 +426,8 @@ Runs `jenkins-jobs update` to update production job configuration
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)

+    :submodule-disable: Disable submodule checkout operation.
+        (default: false)

 
     :gerrit_merge_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths which can be used to
 
     :gerrit_merge_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths which can be used to


@@ -474,6 +471,8 @@ Runs `jenkins-jobs test` to validate JJB syntax
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)

+    :submodule-disable: Disable submodule checkout operation.
+        (default: false)

     :throttle_categories: List of categories to throttle by.
     :throttle-enabled: Whether or not to enable throttling on the job.
         (default: true)
     :throttle_categories: List of categories to throttle by.
     :throttle-enabled: Whether or not to enable throttling on the job.
         (default: true)


@@ -528,7 +527,7 @@ Info YAML Verify
 
 Info YAML Verify job validates that INFO.yaml file changes are kept isolated from
 other file changes. Verifies INFO.yaml files follow the schema defined in
 
 Info YAML Verify job validates that INFO.yaml file changes are kept isolated from
 other file changes. Verifies INFO.yaml files follow the schema defined in

-`global-jjb/info-schema`.
+`lfit/releng-global-jjb/schema/info-schema.yaml`.

 
 :Template Names:
     - {project-name}-info-yaml-verify
 
 :Template Names:
     - {project-name}-info-yaml-verify


@@ -553,6 +552,8 @@ other file changes. Verifies INFO.yaml files follow the schema defined in
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)

+    :submodule-disable: Disable submodule checkout operation.
+        (default: false)

 
     :gerrit_verify_triggers: Override Gerrit Triggers.
 
 
     :gerrit_verify_triggers: Override Gerrit Triggers.
 


@@ -636,6 +637,8 @@ containing the credentials for the cloud.
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)

+    :submodule-disable: Disable submodule checkout operation.
+        (default: false)

 
 Minimal Example:
 
 
 Minimal Example:
 


@@ -645,6 +648,71 @@ Full Example:
 
 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-full.yaml
 
 
 .. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-cron-full.yaml
 

+.. _gjjb-openstack-update-cloud-image:
+
+OpenStack Update Cloud Image
+----------------------------
+
+This job finds and updates OpenStack cloud images on the ci-management source
+repository.
+
+The job is triggered in two ways:
+
+1. When packer merge job completes, the new image name created is passed
+   down to the job.
+2. When the job is triggered manually to update all new images.
+
+When the job is triggered through an upstream packer merge job, this only
+generates a change request for the new image built.
+
+When the job is triggered manually, this job finds the latest images on
+OpenStack cloud and compares them with the images currently used in the source
+ci-management source repository. If the compared images have newer
+time stamps are **all** updated through a change request.
+
+This job requires a Jenkins configuration merge and verify job setup and
+working on Jenkins.
+
+:Template Names:
+    - {project-name}-openstack-update-cloud-image
+    - gerrit-openstack-update-cloud-image
+    - github-openstack-update-cloud-image
+
+:Required parameters:
+
+    :build-node: The node to run build on.
+    :jenkins-ssh-credential: Credential to use for SSH. (Generally should
+        be configured in defaults.yaml)
+    :new-image-name: Name of new image name passed from packer merge job or
+        set to 'all' to update all images. (default: all)
+
+:Optional parameters:
+
+    :branch: Git branch to fetch for the build. (default: master)
+    :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
+    :build-timeout: Timeout in minutes before aborting build. (default: 90)
+    :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
+    :openstack-cloud: OS_CLOUD setting to pass to openstack client.
+        (default: vex)
+    :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.
+        (default: true)
+    :submodule-timeout: Timeout (in minutes) for checkout operation.
+        (default: 10)
+    :submodule-disable: Disable submodule checkout operation.
+        (default: false)
+    :update-cloud-image: Submit a change request to update new built cloud
+        image to Jenkins. (default: false)
+
+Minimal Example:
+
+.. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-update-cloud-image-minimal.yaml
+
+Full Example:
+
+.. literalinclude:: ../../.jjb-test/lf-ci-jobs/openstack-update-cloud-image-full.yaml
+

 
 .. _gjjb-packer-merge:
 
 
 .. _gjjb-packer-merge:
 


@@ -691,8 +759,13 @@ Packer Merge job runs `packer build` to build system images in the cloud.
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)

+    :submodule-disable: Disable submodule checkout operation.
+        (default: false)

 
     :gerrit_verify_triggers: Override Gerrit Triggers.
 
     :gerrit_verify_triggers: Override Gerrit Triggers.

+    :update-cloud-image: Submit a change request to update new built cloud
+        image to Jenkins. (default: false)
+

 
 Test an in-progress patch
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Test an in-progress patch
 ^^^^^^^^^^^^^^^^^^^^^^^^^


@@ -748,6 +821,8 @@ Packer Verify job runs `packer validate` to verify packer configuration.
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)

+    :submodule-disable: Disable submodule checkout operation.
+        (default: false)

 
     :gerrit_verify_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths which can be used to
 
     :gerrit_verify_triggers: Override Gerrit Triggers.
     :gerrit_trigger_file_paths: Override file paths which can be used to


@@ -795,3 +870,76 @@ the base directory is usually the best place to run from.
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)
         (default: true)
     :submodule-timeout: Timeout (in minutes) for checkout operation.
         (default: 10)

+    :submodule-disable: Disable submodule checkout operation.
+        (default: false)
+
+
+Sonar
+-----
+
+Runs Jenkins Sonarqube plug-in to review for bugs, code smells,
+and security vulnerabilities.
+
+Requires ``SonarQube Scanner for Jenkins``
+
+Plug-in configurations
+    Manage Jenkins --> Configure System --> SonarQube servers
+        - Name: Sonar (fixed)
+        - Server URL: https://sonar.server.org/ or https://sonarcloud.io
+        - Server authentication token: none for local, API token (saved as a
+          "secret text" credential) for Sonarcloud
+
+    Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
+        - Name: SonarQube Scanner (fixed)
+        - Install automatically
+        - Select latest version
+
+.. note:: Sonar properties can be set directly in the job definition by
+   setting the sonar-project-file to ``""`` and adding all properties under
+   ``sonar-properties``.
+
+:Template Names:
+
+    - {project-name}-sonar
+    - gerrit-sonar
+    - github-sonar
+
+:Optional Parameters:
+    :sonar-task: Sonar task to run. (default: "")
+    :sonar-project-file: The filename for the project's properties
+        (default: "sonar-project.properties")
+    :sonar-properties: Sonar configuration properties. (default: "")
+    :sonar-java-opts: JVM options. (default: "")
+    :sonar-additional-args: Additional command line arguments. (default: "")
+
+
+Sonar with Prescan
+------------------
+
+The same as the Sonar job above, except the caller also defines a builder
+called ``lf-sonar-prescan``, in which they can put any builders that they want
+to run prior to the Sonar scan.
+
+.. code-block:: yaml
+
+   - builder:
+       name: lf-sonar-prescan
+       builders:
+         - shell: "# Pre-scan shell script"
+
+:Template Names:
+
+    - {project-name}-sonar-prescan
+    - gerrit-sonar-prescan
+    - github-sonar-prescan
+
+:Required Parameters:
+    :lf-sonar-prescan: A builder that will run prior to the Sonar scan.
+
+:Optional Parameters:
+    :sonar-task: Sonar task to run. (default: "")
+    :sonar-project-file: The filename for the project's properties
+        (default: "sonar-project.properties")
+    :sonar-properties: Sonar configuration properties. (default: "")
+    :sonar-java-opts: JVM options. (default: "")
+    :sonar-additional-args: Additional command line arguments. (default: "")