feat: tag normalization

README.md

@@ -69,7 +69,7 @@ The **snapshot** and **release** images are defined by the following variables:
 
 | Name                      | description           | default value                                     |
 | ------------------------- | --------------------- | ------------------------------------------------- |
-| `DOCKER_SNAPSHOT_IMAGE`   | Docker snapshot image | `$CI_REGISTRY_IMAGE/snapshot:$CI_COMMIT_REF_SLUG` |
+| `DOCKER_SNAPSHOT_IMAGE`   | Docker snapshot image | `$CI_REGISTRY_IMAGE/snapshot:$CI_COMMIT_REF_NAME` |
 | `DOCKER_RELEASE_IMAGE`    | Docker release image  | `$CI_REGISTRY_IMAGE:$CI_COMMIT_REF_NAME`          |
 
 As you can see, the Docker template is configured by default to use the GitLab container registry.
@@ -77,9 +77,24 @@ You may perfectly override this and use another Docker registry, but be aware of
 
 * the `DOCKER_SNAPSHOT_IMAGE` requires a Docker registry that allows tag overwrite,
 * the `DOCKER_RELEASE_IMAGE` _may_ use a Docker registry that doesn't allow tag overwrite, but:
-    1. you should avoid overwriting a Git tag (at it will obviously fail while trying to (re)push the Docker image),
+    1. you should avoid overwriting a Git tag (as it will obviously fail while trying to (re)push the Docker image),
     2. you have to deactivate publish on `master` branch by setting the `$PUBLISH_ON_PROD` variable to `false` (as it would lead to the `master` tag being overwritten).
 
+#### Which tag to use?
+
+By default, the Docker template uses `$CI_COMMIT_REF_NAME` as image tags.
+It has advantages (the tag is meaningful to you, especially when releasing via a Git tag) and drawbacks (compels using a Docker registry that allows tag overwrite; when continuously deploying the image, it may be tough to force redeploying the container when the image 
+name didn't change).
+
+Depending on your context, you may prefer using another tagging policy. 
+For instance `$CI_COMMIT_TIMESTAMP` might be a good alternative.
+
+Whichever your choice, the Docker template normalizes the tag value so that it complies to the [standard syntax](https://docs.docker.com/engine/reference/commandline/tag/#extended-description):
+
+> A tag name must be valid ASCII and may contain lowercase and uppercase letters, digits, underscores, periods and dashes. A tag name may not start with a period or a dash and may contain a maximum of 128 characters.
+
+The Docker template simply replaces any forbidden character with a dash (`-`).
+
 ### Registries and credentials
 
 As seen in the previous chapter, the Docker template uses by default the GitLab registry to push snapshot and release images.

kicker.json

@@ -37,7 +37,7 @@
     {
       "name": "DOCKER_SNAPSHOT_IMAGE",
       "description": "Docker snapshot image",
-      "default": "$CI_REGISTRY_IMAGE/snapshot:$CI_COMMIT_REF_SLUG"
+      "default": "$CI_REGISTRY_IMAGE/snapshot:$CI_COMMIT_REF_NAME"
     },
     {
       "name": "DOCKER_RELEASE_IMAGE",

templates/gitlab-ci-docker.yml

@@ -29,7 +29,7 @@ variables:
   DOCKER_HEALTHCHECK_TIMEOUT: "60"
 
   # Default Docker config uses the internal GitLab registry
-  DOCKER_SNAPSHOT_IMAGE: "$CI_REGISTRY_IMAGE/snapshot:$CI_COMMIT_REF_SLUG"
+  DOCKER_SNAPSHOT_IMAGE: "$CI_REGISTRY_IMAGE/snapshot:$CI_COMMIT_REF_NAME"
   DOCKER_RELEASE_IMAGE: "$CI_REGISTRY_IMAGE:$CI_COMMIT_REF_NAME"
 
   DOCKER_KANIKO_VERBOSITY: "info"
@@ -269,6 +269,29 @@ stages:
     done
   }
 
+  function normalize_image() {
+    imgprefix=${1%%:*}
+    tagonly=${1#*:}
+    normtag=${tagonly//[^a-zA-Z0-9_\.-]/-}
+    echo "$imgprefix:$normtag"
+  }
+
+  function normalize_images() {
+    norm_snapshot_img=$(normalize_image "$DOCKER_SNAPSHOT_IMAGE")
+    if [[ "$norm_snapshot_img" != "$DOCKER_SNAPSHOT_IMAGE" ]]
+    then
+      export DOCKER_SNAPSHOT_IMAGE="$norm_snapshot_img"
+      log_info "Normalized snapshot image: $DOCKER_SNAPSHOT_IMAGE"
+    fi
+
+    norm_release_img=$(normalize_image "$DOCKER_RELEASE_IMAGE")
+    if [[ "$norm_release_img" != "$DOCKER_RELEASE_IMAGE" ]]
+    then
+      export DOCKER_RELEASE_IMAGE="$norm_release_img"
+      log_info "Normalized release image: $DOCKER_RELEASE_IMAGE"
+    fi
+  }
+
   function is_runner_dind_capable() {
     docker info > /dev/null 2>&1
   }
@@ -277,7 +300,6 @@ stages:
     docker_snapshot_authent_token=$(echo -n "${DOCKER_REGISTRY_SNAPSHOT_USER:-${DOCKER_REGISTRY_USER:-$CI_REGISTRY_USER}}:${DOCKER_REGISTRY_SNAPSHOT_PASSWORD:-${DOCKER_REGISTRY_PASSWORD:-$CI_REGISTRY_PASSWORD}}" | base64 | tr -d '\n')
     docker_snapshot_registry_host=$(echo "$DOCKER_SNAPSHOT_IMAGE" | cut -d/ -f1)
 
-
     docker_release_authent_token=$(echo -n "${DOCKER_REGISTRY_RELEASE_USER:-${DOCKER_REGISTRY_USER:-$CI_REGISTRY_USER}}:${DOCKER_REGISTRY_RELEASE_PASSWORD:-${DOCKER_REGISTRY_PASSWORD:-$CI_REGISTRY_PASSWORD}}" | base64 | tr -d '\n')
     docker_release_registry_host=$(echo "$DOCKER_RELEASE_IMAGE" | cut -d/ -f1)
 
@@ -321,6 +343,7 @@ stages:
     install_custom_ca_certs
     unscope_variables
     eval_all_secrets
+    normalize_images
     configure_registries_auth
 
     if is_runner_dind_capable