From 6ea3312668c61c69eb2390a6d05a2dd61f3119d7 Mon Sep 17 00:00:00 2001 From: "Lott, Christopher (cl778h)" Date: Tue, 10 Dec 2019 14:04:06 -0500 Subject: [PATCH] Revise docker-get-container-tag-script macro Silence JJB warning by calling include-raw (not include-raw-escape) when pulling in shell-script content; the result is the same. Extend the documentation for the supported methods. Add details on the contract of the shell script. Change-Id: I6de0746653d3ceaf6df9fc63eb7aff5259f4b062 Signed-off-by: Lott, Christopher (cl778h) --- docs/jjb/lf-docker-jobs.rst | 50 ++++++++++++++++------ jjb/lf-docker-jobs.yaml | 2 +- ...get-container-tag-include-2c81e313686816c7.yaml | 6 +++ 3 files changed, 45 insertions(+), 13 deletions(-) create mode 100644 releasenotes/notes/refactor-docker-get-container-tag-include-2c81e313686816c7.yaml diff --git a/docs/jjb/lf-docker-jobs.rst b/docs/jjb/lf-docker-jobs.rst index 09abbbb8..ba65b29d 100644 --- a/docs/jjb/lf-docker-jobs.rst +++ b/docs/jjb/lf-docker-jobs.rst @@ -19,16 +19,42 @@ Macros lf-docker-get-container-tag --------------------------- -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. Optionally, teams can call their own script to -handle the docker tagging differently. +Chooses a tag to label the container image based on the +'container-tag-method' parameter using the global-jjb script +docker-get-container-tag.sh. Use one of the following methods: + +If container-tag-method: latest, the literal string 'latest' is used. + +If container-tag-method: git-describe, the tag is obtained using the +git describe command on the repository, which requires that the repository +has a git tag. For example, if the most recent tag is 'v0.48.1', this +method yields a string like 'v0.48.1' or 'v0.48.1-25-gaee2dcb'. + +If container-tag-method: yaml-file, the tag is obtained from the YAML file +'container-tag.yaml' in the docker-root directory using the top-level entry +'tag'. Alternately specify the directory with the YAML file in parameter +'container-tag-yaml-dir'. An example file appears next. + +Example container-tag.yaml file: + +.. code-block:: yaml + + --- + tag: 1.0.0 + + +Optionally, teams can supply their own script to choose the docker +tag. Pass the shell script path in optional configuration parameter +'docker-get-container-tag-script' which by default is the path to +file docker-get-container-tag.sh. The script must create the file +'env_docker_inject.txt' in the workspace with a line that assigns a +value to shell variable DOCKER_IMAGE_TAG, as shown next. + +Example env_docker_inject.txt file: + +.. code-block:: shell + + DOCKER_IMAGE_TAG=1.0.0 lf-docker-build @@ -80,7 +106,7 @@ Executes a docker build task. (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-get-container-tag-script: Pointer to script to handle docker tags. + :docker-get-container-tag-script: Path to script that chooses docker tag. (default: ../shell/docker-get-container-tag.sh) :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root) :git-url: URL clone project from. (default: $GIT_URL/$PROJECT) @@ -151,7 +177,7 @@ Executes a docker build task and publishes the resulting images to a specified D 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-get-container-tag-script: Pointer to script to handle docker tags. + :docker-get-container-tag-script: Path to script that chooses docker tag. (default: ../shell/docker-get-container-tag.sh) :docker-root: Build directory within the repo. (default: $WORKSPACE, the repo root) :git-url: URL clone project from. (default: $GIT_URL/$PROJECT) diff --git a/jjb/lf-docker-jobs.yaml b/jjb/lf-docker-jobs.yaml index bc522ca2..402d8678 100644 --- a/jjb/lf-docker-jobs.yaml +++ b/jjb/lf-docker-jobs.yaml @@ -13,7 +13,7 @@ CONTAINER_TAG_METHOD={container-tag-method} CONTAINER_TAG_YAML_DIR={container-tag-yaml-dir} DOCKER_ROOT={docker-root} - - shell: !include-raw-escape: "{docker-get-container-tag-script}" + - shell: !include-raw: "{docker-get-container-tag-script}" - inject: # Import the container tag set by this build step properties-file: "env_docker_inject.txt" diff --git a/releasenotes/notes/refactor-docker-get-container-tag-include-2c81e313686816c7.yaml b/releasenotes/notes/refactor-docker-get-container-tag-include-2c81e313686816c7.yaml new file mode 100644 index 00000000..5c156cfa --- /dev/null +++ b/releasenotes/notes/refactor-docker-get-container-tag-include-2c81e313686816c7.yaml @@ -0,0 +1,6 @@ +--- +fixes: + - | + Revise the lf-docker-get-container-tag macro to use include-raw, + not include-raw-escape, to silence JJB warning. + Improve documentation of lf-docker-get-container-tag macro. -- 2.16.6