Update docker job templates gerrit trigger regexes
[releng/global-jjb.git] / docs / jjb / lf-docker-jobs.rst
index b661f52..354c77e 100644 (file)
@@ -19,8 +19,16 @@ Macros
 lf-docker-get-container-tag
 ---------------------------
 
-Calls docker-get-git-describe.sh or docker-get-yaml-tag.sh (depending on the
-'docker-use-params-from' condition) to obtain the tag to build.
+Chooses a container tag to label the image based on the 'container-tag-method'
+parameter.  If container-tag-method: latest, the tag 'latest' is used.
+If container-tag-method: git-describe, the tag is obtained using
+the git describe command, which requires that the repository has a git tag.
+If container-tag-method: yaml-file, the tag is obtained using
+the yq command, which requires that the repository has a YAML file named
+'container-tag.yaml'. The script checks the docker-root directory by
+default or the directory specified by parameter container-tag-yaml-dir.
+An example file appears below.
+
 
 lf-docker-build
 ---------------
@@ -46,16 +54,15 @@ Executes a docker build task.
     - gerrit-docker-verify
     - github-docker-verify
 
-:Comment Trigger: recheck|reverify
+:Comment Trigger: **recheck|reverify** post a comment with one of the
+    triggers to launch this job manually. Do not include any additional
+    text or vote in the same comment.
 
 :Required parameters:
 
     :build-node: The node to run build on.
     :container-public-registry: Docker registry source with base images.
     :docker-name: Name of the Docker image.
-    :docker-use-params-from: Used to select the source of the tag information.
-        Options are "git-describe-params" or "yaml-file-params". (yaml-file-params
-        expects the tag to be defined in a local file "container-tag.yaml").
     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
         be configured in defaults.yaml)
     :mvn-settings: Maven settings.xml file containing credentials to use.
@@ -65,13 +72,19 @@ Executes a docker build task.
     :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: 60)
+    :container-tag-method: Specifies the docker tag-choosing method.
+        Options are "latest", "git-describe" or "yaml-file".
+        Option git-describe requires a git tag to exist in the repository.
+        Option yaml-file requires a file "container-tag.yaml" to exist in the repository.
+        (default: latest)
+    :container-tag-yaml-dir: Directory with container-tag.yaml. (default: $DOCKER_ROOT)
     :docker-build-args: Additional arguments for the docker build command.
-    :docker-root: Path of the Dockerfile within the repo.
+    :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
-    :pre_docker_build_script: Optional build script to execute before the main verify
-        builder steps.
-    :post_docker_build_script: Optional build script to execute after the main verify
-        builder steps.
+    :pre_docker_build_script: Build script to execute before the main verify
+        builder steps. (default: a string with only a comment)
+    :post_docker_build_script: Build script to execute after the main verify
+        builder steps. (default: a string with only a comment)
     :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.
@@ -105,7 +118,9 @@ Executes a docker build task and publishes the resulting images to a specified D
     - gerrit-docker-merge
     - github-docker-merge
 
-:Comment Trigger: remerge
+:Comment Trigger: **remerge** post a comment with the trigger to launch
+    this job manually. Do not include any additional text or vote in the
+    same comment.
 
 :Required parameters:
 
@@ -113,9 +128,6 @@ Executes a docker build task and publishes the resulting images to a specified D
     :container-public-registry: Docker registry source with base images.
     :container-push-registry: Docker registry target for the deploy action.
     :docker-name: Name of the Docker image.
-    :docker-use-params-from: Used to select the source of the tag information.
-        Options are "git-describe-params" or "yaml-file-params". (yaml-file-params
-        expects the tag to be defined in a local file "container-tag.yaml").
     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
         be configured in defaults.yaml)
     :mvn-settings: Maven settings.xml file containing credentials to use.
@@ -125,17 +137,23 @@ Executes a docker build task and publishes the resulting images to a specified D
     :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: 60)
+    :container-tag-method: Specifies the docker tag-choosing method.
+        Options are "latest", "git-describe" or "yaml-file".
+        Option git-describe requires a git tag to exist in the repository.
+        Option yaml-file requires a file "container-tag.yaml" to exist in the repository.
+        (default: latest)
+    :container-tag-yaml-dir: Directory with container-tag.yaml. (default: $DOCKER_ROOT)
     :cron: Cron schedule when to trigger the job. This parameter also
         supports multiline input via YAML pipe | character in cases where
         one may want to provide more than 1 cron timer. No default. Use
         '@daily' to run daily or 'H H * * 0' to run weekly.
     :docker-build-args: Additional arguments for the docker build command.
-    :docker-root: Path of the Dockerfile within the repo.
+    :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root)
     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
-    :pre_docker_build_script: Optional build script to execute before the main merge
-        builder steps.
-    :post_docker_build_script: Optional build script to execute after the main merge
-        builder steps.
+    :pre_docker_build_script: Build script to execute before the main merge
+        builder steps. (default: a string with only a comment)
+    :post_docker_build_script: Build script to execute after the main merge
+        builder steps. (default: a string with only a comment)
     :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.
@@ -150,7 +168,8 @@ Executes a docker build task and publishes the resulting images to a specified D
         used to filter which file modifications will trigger a build;
         must match parameter gerrit_trigger_file_paths
 
-container-tag.yaml example:
+Sample container-tag.yaml File
+------------------------------
 
 .. code-block:: yaml