push
To load these rules, add this to the top of your BUILD
file:
load("@rules_oci//oci:defs.bzl", ...)
Rules
oci_push_rule
Push an oci_image or oci_image_index to a remote registry.
Internal rule used by the oci_push macro. Most users should use the macro.
Authorization
By default, oci_push uses the standard authorization config file located on the host where oci_push
is running.
Therefore the following documentation may be consulted:
- https://docs.docker.com/engine/reference/commandline/login/
- https://docs.podman.io/en/latest/markdown/podman-login.1.html
- https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane_auth_login.md
Behavior
Pushing and tagging are performed sequentially which MAY lead to non-atomic pushes if one the following events occur;
- Remote registry rejects a tag due to various reasons. eg: forbidden characters, existing tags
- Remote registry closes the connection during the tagging
- Local network outages
In order to avoid incomplete pushes oci_push will push the image by its digest and then apply the remote_tags
sequentially at
the remote registry.
Any failure during pushing or tagging will be reported with non-zero exit code and cause remaining steps to be skipped.
Usage
When running the pusher, you can pass flags to bazel run
.
- Override
repository
by passing the-r|--repository
flag.
e.g. bazel run //myimage:push -- --repository index.docker.io/<ORG>/image
- Supply tags in addition to
remote_tags
by passing the-t|--tag
flag.
e.g. bazel run //myimage:push -- --tag latest
Examples
Push an oci_image to docker registry with 'latest' tag
oci_image(name = "image")
oci_push(
name = "push",
image = ":image",
repository = "index.docker.io/<ORG>/image",
remote_tags = ["latest"]
)
Push a multi-architecture image to github container registry with a semver tag
load("@aspect_bazel_lib//lib:expand_template.bzl", "expand_template_rule")
oci_image(name = "app_linux_arm64")
oci_image(name = "app_linux_amd64")
oci_image(name = "app_windows_amd64")
oci_image_index(
name = "app_image",
images = [
":app_linux_arm64",
":app_linux_amd64",
":app_windows_amd64",
]
)
# Use the value of --embed_label under --stamp, otherwise use a deterministic constant
# value to ensure cache hits for actions that depend on this.
expand_template(
name = "stamped",
out = "_stamped.tags.txt",
template = ["0.0.0"],
stamp_substitutions = {"0.0.0": "{{BUILD_EMBED_LABEL}}"},
)
oci_push(
name = "push",
image = ":app_image",
repository = "ghcr.io/<OWNER>/image",
remote_tags = ":stamped",
)
To push to more than one registry, or using multiple remote tags, use rules_multirun to group multiple oci_push targets into one executable target.
For example:
load("@rules_multirun//:defs.bzl", "command", "multirun")
REPOS = {
"index": "index.docker.io/<ORG>/image",
"ECR": "aws_account_id.dkr.ecr.us-west-2.amazonaws.com",
}
[
oci_push(
name = "push_image_" + k,
image = ":image_index",
remote_tags = ":stamped",
repository = v,
)
for (k, v) in REPOS.items()
]
[
command(
name = k,
command = "push_image_" + k,
)
for k in REPOS.keys()
]
multirun(
name = "push_all",
commands = REPOS.keys(),
)
Example usage (generated):
load("@rules_oci//oci:defs.bzl", "oci_push_rule")
oci_push_rule(
# A unique name for this target.
name = "",
# Label to an oci_image or oci_image_index
image = "",
)
name
Required name.
A unique name for this target.
image
Required label.
Label to an oci_image or oci_image_index
repository
Optional string.
Default: ""
Repository URL where the image will be signed at, e.g.: index.docker.io/<user>/image
.
Digests and tags are not allowed.
repository_file
Optional label.
Default: None
The same as 'repository' but in a file. This allows pushing to different repositories based on stamping.
remote_tags
Optional label.
Default: None
a .txt file containing tags, one per line.
These are passed to crane tag
Macros and Functions
oci_push
Macro wrapper around oci_push_rule.
Allows the remote_tags attribute to be a list of strings in addition to a text file.
Example usage (generated):
load("@rules_oci//oci:defs.bzl", "oci_push")
oci_push(
# name of resulting oci_push_rule
name = "",
)
name
Required.
name of resulting oci_push_rule
remote_tags
Optional. Default: None
a list of tags to apply to the image after pushing, or a label of a file containing tags one-per-line. See stamped_tags as one example of a way to produce such a file.
kwargs
Optional.
other named arguments to oci_push_rule and common rule attributes.