Merge branch '3.1.x'

Closes gh-38354

Author: mhalbritter

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc

@@ -1,6 +1,6 @@
 [[spring-boot-gradle-plugin-documentation]]
 = Spring Boot Gradle Plugin Reference Guide
-Andy Wilkinson; Scott Frederick
+Andy Wilkinson; Scott Frederick; Moritz Halbritter
 v{gradle-project-version}
 :!version-label:
 :doctype: book

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc

@@ -190,7 +190,8 @@ The value supplied will be passed unvalidated to Docker when creating the builde
 | `tags`
 |
 | A list of one or more additional tags to apply to the generated image.
-The values provided to the `tags` option should be full image references in the form of `[image name]:[tag]` or `[repository]/[image name]:[tag]`.
+The values provided to the `tags` option should be *full* image references.
+See <<build-image.customization.tags, the tags section>> for more details.
 |
 
 | `buildWorkspace`
@@ -236,6 +237,24 @@ You can override this behaviour as shown in the <<build-image.examples.builder-c
 
 
 
+[[build-image.customization.tags]]
+=== Tags format
+
+The values provided to the `tags` option should be *full* image references.
+The accepted format is `[domainHost:port/][path/]name[:tag][@digest]`.
+
+If the domain is missing, it defaults to `docker.io`.
+If the path is missing, it defaults to `library`.
+If the tag is missing, it defaults to `latest`.
+
+Some examples:
+
+* `my-image` leads to the image reference `docker.io/library/my-image:latest`
+* `my-repository/my-image` leads to `docker.io/my-repository/my-image:latest`
+* `example.com/my-repository/my-image:1.0.0` will be used as is
+
+
+
 [[build-image.examples]]
 == Examples
 

spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc

@@ -199,7 +199,8 @@ The value supplied will be passed unvalidated to Docker when creating the builde
 
 | `tags`
 | One or more additional tags to apply to the generated image.
-The values provided to the `tags` option should be full image references in the form of `[image name]:[tag]` or `[repository]/[image name]:[tag]`.
+The values provided to the `tags` option should be *full* image references.
+See <<build-image.customization.tags, the tags section>> for more details.
 |
 
 | `buildWorkspace`
@@ -242,6 +243,24 @@ You can override this behaviour as shown in the <<build-image.examples.builder-c
 
 For more details, see also <<build-image.examples,examples>>.
 
+
+
+[[build-image.customization.tags]]
+=== Tags format
+
+The values provided to the `tags` option should be *full* image references.
+The accepted format is `[domainHost:port/][path/]name[:tag][@digest]`.
+
+If the domain is missing, it defaults to `docker.io`.
+If the path is missing, it defaults to `library`.
+If the tag is missing, it defaults to `latest`.
+
+Some examples:
+
+* `my-image` leads to the image reference `docker.io/library/my-image:latest`
+* `my-repository/my-image` leads to `docker.io/my-repository/my-image:latest`
+* `example.com/my-repository/my-image:1.0.0` will be used as is
+
 include::goals/build-image.adoc[leveloffset=+1]
 include::goals/build-image-no-fork.adoc[leveloffset=+1]