Skip to main content
The hud push command publishes your environment image to a Docker registry and uploads metadata to the HUD registry.

​
Usage

hud push [DIRECTORY] [OPTIONS]

​
Arguments

​
directory
string
default:"."
Environment directory containing hud.lock.yaml

​
Options

​
--image
string
Override registry image name (e.g., myorg/myenv). Short: -i
​
--tag
string
Override tag (e.g., v1.0, latest). Short: -t
​
--sign
boolean
default:"false"
Sign the image with cosign (not yet implemented)
​
--yes
boolean
default:"false"
Skip confirmation prompts. Short: -y
​
--verbose
boolean
default:"false"
Show detailed output. Short: -v

​
Prerequisites

Requires HUD_API_KEY:
export HUD_API_KEY="your-api-key"
Login to your Docker registry first (e.g., Docker Hub or GHCR):
docker login
# or
docker login ghcr.io

​
What It Does

1

Verify Build

Ensures a recent hud build exists (lock file present), prompting to build if missing.
2

Choose Target

Determines target image:
  • --image if provided
  • Else auto-detects Docker Hub username and uses username/{name}:{tag}
  • Tag uses --tag, or the lock’s internal build.version, else current tag
3

Push Image

Tags and pushes via Docker; captures pushed digest.
4

Update Lock

Updates hud.lock.yaml with:
  • image: full registry reference with digest
  • push: source, pushedAt, registry, and image_with_tag
5

Upload Metadata

Uploads lock metadata to the HUD registry path .../registry/envs/{org}/{name}:{tag}.

​
Registry Detection

  1. Explicit --image → used as‑is.
  2. Docker config → reads logged‑in username (Docker Hub).
  3. Default → prompts if no login and --image missing.

​
Examples

# Basic (auto username)
hud push

# Custom registry and tag
hud push . --image ghcr.io/myorg/myenv --tag v1.0.0

# Non‑interactive (CI)
hud push . --yes --tag "prod-$(date +%Y%m%d)"

​
Lock File After Push

image: "myorg/myenv:latest@sha256:..."
push:
  source: "my-env:dev@sha256:..."
  pushedAt: "2025-01-01T11:00:00Z"
  registry: "ghcr.io"
  image_with_tag: "myorg/myenv:latest"

​
Notes

  • If HUD registry upload fails, the Docker push still succeeds; you can share hud.lock.yaml manually.
  • Image names must include org/name for HUD registry uploads.

​
See Also