container_push: add doc about no transaction

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 |