push.md

Public API for container image push rules.

image_push

load("@rules_img//img:push.bzl", "image_push")

image_push(name, build_settings, image, registry, repository, stamp, strategy, tag, tag_file,
           tag_list)

Pushes container images to a registry.

This rule creates an executable target that uploads OCI images to container registries. It supports multiple push strategies optimized for different use cases, from simple uploads to advanced content-addressable storage integration.

Key features:

• Multiple push strategies: Choose between eager, lazy, CAS-based, or BES-integrated pushing
• Template expansion: Dynamic registry, repository, and tag values using build settings
• Stamping support: Include build information in image tags
• Incremental uploads: Skip blobs that already exist in the registry

The rule produces an executable that can be run with bazel run.

Example:

load("@rules_img//img:push.bzl", "image_push")

# Simple push to Docker Hub
image_push(
    name = "push_app",
    image = ":my_app",
    registry = "index.docker.io",
    repository = "myorg/myapp",
    tag = "latest",
)

# Push multi-platform image with multiple tags
image_push(
    name = "push_multiarch",
    image = ":my_app_index",  # References an image_index
    registry = "gcr.io",
    repository = "my-project/my-app",
    tag_list = ["latest", "v1.0.0"],
)

# Dynamic push with build settings
image_push(
    name = "push_dynamic",
    image = ":my_app",
    registry = "{{.REGISTRY}}",
    repository = "{{.PROJECT}}/my-app",
    tag = "{{.VERSION}}",
    build_settings = {
        "REGISTRY": "//settings:registry",
        "PROJECT": "//settings:project",
        "VERSION": "//settings:version",
    },
)

# Push with stamping for unique tags
image_push(
    name = "push_stamped",
    image = ":my_app",
    registry = "index.docker.io",
    repository = "myorg/myapp",
    tag = "latest-{{.BUILD_TIMESTAMP}}",
    stamp = "enabled",
)

# Digest-only push (no tag)
image_push(
    name = "push_by_digest",
    image = ":my_app",
    registry = "gcr.io",
    repository = "my-project/my-app",
    # No tag specified - will push by digest only
)

Push strategies:

• eager: Materializes all layers next to push binary. Simple, correct, but may be inefficient.
• lazy: Layers are not stored locally. Missing layers are streamed from Bazel's remote cache.
• cas_registry: Uses content-addressable storage for extreme efficiency. Requires CAS-enabled infrastructure.
• bes: Image is pushed as side-effect of Build Event Stream upload. No "bazel run" command needed. Requires Build Event Service integration.

See push strategies documentation for detailed comparisons.

Runtime usage:

# Push to registry
bazel run //path/to:push_app

# The push command will output the image digest

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
build_settings	Build settings for template expansion. Maps template variable names to string_flag targets. These values can be used in registry, repository, and tag attributes using {{.VARIABLE_NAME}} syntax (Go template). Example: build_settings = { "REGISTRY": "//settings:docker_registry", "VERSION": "//settings:app_version", } See template expansion for more details.	Dictionary: String -> Label	optional	{}
image	Image to push. Should provide ImageManifestInfo or ImageIndexInfo.	Label	required
registry	Registry URL to push the image to. Common registries: - Docker Hub: index.docker.io - Google Container Registry: gcr.io or us.gcr.io - GitHub Container Registry: ghcr.io - Amazon ECR: 123456789.dkr.ecr.us-east-1.amazonaws.com Subject to template expansion.	String	optional	""
repository	Repository path within the registry. Subject to template expansion.	String	optional	""
stamp	Enable build stamping for template expansion. Controls whether to include volatile build information: - auto (default): Uses the global stamping configuration - enabled: Always include stamp information (BUILD_TIMESTAMP, BUILD_USER, etc.) if Bazel's "--stamp" flag is set - disabled: Never include stamp information See template expansion for available stamp variables.	String	optional	"auto"
strategy	Push strategy to use. See push strategies documentation for detailed information.	String	optional	"auto"
tag	Tag to apply to the pushed image. Optional - if omitted, the image is pushed by digest only. Subject to template expansion.	String	optional	""
tag_file	File containing newline-delimited tags to apply to the pushed image. The file should contain one tag per line. Empty lines are ignored. Tags from this file are merged with tags specified via tag or tag_list attributes. Example file content: latest v1.0.0 stable Can be combined with tag or tag_list to merge tags from multiple sources. Each tag is subject to template expansion.	Label	optional	None
tag_list	List of tags to apply to the pushed image. Useful for applying multiple tags in a single push: tag_list = ["latest", "v1.0.0", "stable"] Cannot be used together with tag. Can be combined with tag_file to merge tags from both sources. Each tag is subject to template expansion.	List of strings	optional	[]