container_push: add doc about no transaction

When use container_push with skip_unchanged_digest,
user often rely on the push process to (1) check for existence
of the image in the registry and (2) push the image if (1) is false.

This leave a time window between (1) and (2) where the image
could have been pushed by an external process such as another CI
job running in parallel. In such situation, depends on the container
registry configuration, the push arrive later can either fail for attempting
to override an already pushed image, or it will override the previously
pushed image.

There is no transactional guarantee that can help coordinate (1) and (2) in
the current container registry spec. So let's document this edge case and
advise users to work around by using some external distributed lock for
running container_push target.

container/push.bzl

@@ -170,7 +170,10 @@ container_push_ = rule(
         ),
         "skip_unchanged_digest": attr.bool(
             default = False,
-            doc = "Only push images if the digest has changed, default to False",
+            doc = "Check if the container registry already contain the image's digest. If yes, skip the push for that image. " +
+                  "Default to False. " +
+                  "Note that there is no transactional guarantee between checking for digest existence and pushing the digest. " +
+                  "This means that you should try to avoid running the same container_push targets in parallel.",
         ),
         "stamp": STAMP_ATTR,
         "tag": attr.string(

docs/container.md

@@ -241,7 +241,7 @@ container_push(<a href="#container_push-name">name</a>, <a href="#container_push
 | <a id="container_push-registry"></a>registry |  The registry to which we are pushing.   | String | required |  |
 | <a id="container_push-repository"></a>repository |  The name of the image.   | String | required |  |
 | <a id="container_push-repository_file"></a>repository_file |  The label of the file with repository value. Overrides 'repository'.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
-| <a id="container_push-skip_unchanged_digest"></a>skip_unchanged_digest |  Only push images if the digest has changed, default to False   | Boolean | optional | False |
+| <a id="container_push-skip_unchanged_digest"></a>skip_unchanged_digest |  Check if the container registry already contain the image's digest. If yes, skip the push for that image. Default to False. Note that there is no transactional guarantee between checking for digest existence and pushing the digest. This means that you should try to avoid running the same container_push targets in parallel.   | Boolean | optional | False |
 | <a id="container_push-stamp"></a>stamp |  Whether to encode build information into the output. Possible values:<br><br>    - <code>@io_bazel_rules_docker//stamp:always</code>:         Always stamp the build information into the output, even in [--nostamp][stamp] builds.         This setting should be avoided, since it potentially causes cache misses remote caching for         any downstream actions that depend on it.<br><br>    - <code>@io_bazel_rules_docker//stamp:never</code>:         Always replace build information by constant values. This gives good build result caching.<br><br>    - <code>@io_bazel_rules_docker//stamp:use_stamp_flag</code>:         Embedding of build information is controlled by the [--[no]stamp][stamp] flag.         Stamped binaries are not rebuilt unless their dependencies change.<br><br>    [stamp]: https://docs.bazel.build/versions/main/user-manual.html#flag--stamp   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | @io_bazel_rules_docker//stamp:use_stamp_flag |
 | <a id="container_push-tag"></a>tag |  The tag of the image.   | String | optional | "latest" |
 | <a id="container_push-tag_file"></a>tag_file |  The label of the file with tag value. Overrides 'tag'.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |