Q: How do you push a Docker image to a private registry?
docker login <registry>. docker tag myimage:latest <registry>/myimage:latest. docker push <registry>/myimage:latest.
Want to master this scenario in a live sandbox? KodeKloud's Docker Certified Associate (DCA) Hands-On Lab Course covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: To <strong>push a Docker image to a private registry</strong>, authenticate with <code>docker login</code>, tag the image with the registry host in its name, then run <code>docker push</code>. The tag matters because Docker decides where to push by the hostname prefix. Interviewers ask this to check that you understand image naming, credential storage, TLS trust and how clusters later pull the image. Most real failures are one of four things: a missing prefix in the tag, expired credentials, an untrusted certificate, or a repository that does not exist yet.
Understand Image Names and Where a Push to a Private Registry Goes
A reference is registry-host[:port]/namespace/repo:tag, and the host part selects the destination.
- No host means Docker Hub:
my-app:1.0would targetdocker.io/library/my-app, which is almost never what you want. - Tags are mutable: pushing
1.4.2twice overwrites the tag unless the registry enforces immutability; the digest (sha256:...) is the permanent identifier. - Auth is per registry host: credentials are stored by hostname in
~/.docker/config.json, preferably through a credential helper. - Tag is just an alias:
docker tagadds a name to the same image ID; it copies nothing.
Login, Tag and Push
The standard flow for a registry such as Harbor, GitLab, Nexus or a self-hosted registry:2.
echo "$REGISTRY_TOKEN" | docker login registry.example.com -u ci-bot --password-stdin
docker build -t my-app:1.4.2 .
docker tag my-app:1.4.2 registry.example.com/team/my-app:1.4.2
docker push registry.example.com/team/my-app:1.4.2
# 1.4.2: digest: sha256:<digest> size: 1573
# Build and push multi-arch directly
docker buildx build --platform linux/amd64,linux/arm64 \
-t registry.example.com/team/my-app:1.4.2 --push .
- Login without leaking the password: use
--password-stdinso the secret does not land in shell history or the process list. - Tag with the full path: include host, project and version.
- Push and note the digest: the last line of the output prints the digest of the pushed manifest.
- Multi-arch:
docker buildx build --platform linux/amd64,linux/arm64 --pushbuilds and pushes a manifest list in one step.
Verify the Image Landed Correctly
Do not trust the push exit code alone; confirm the manifest from a clean state.
docker buildx imagetools inspect registry.example.com/team/my-app:1.4.2
docker image rm registry.example.com/team/my-app:1.4.2
docker pull registry.example.com/team/my-app@sha256:<digest>
# Kubernetes pull credentials
kubectl create secret docker-registry regcred -n prod \
--docker-server=registry.example.com \
--docker-username=ci-bot --docker-password="$REGISTRY_TOKEN"
# then set imagePullSecrets: [{name: regcred}] on the pod spec
- Inspect remote manifest:
docker buildx imagetools inspectreads the registry without pulling layers and lists platforms. - Pull from a clean host: remove the local copy and pull by digest to prove the registry serves what you pushed.
- Registry API check: a registry v2 endpoint such as
/v2/team/my-app/tags/listlists tags (authentication required). - Cluster pull test: for Kubernetes create a pull secret and run a test pod before relying on it.
Diagnose Common Push Failures
Read the error string; each maps to a specific cause.
denied: requested access to the resource is denied: not logged in, wrong account, no push permission, or the tag lacks the registry prefix and went to Docker Hub.no basic auth credentials: login is missing for that exact hostname, including the port if one is used.x509: certificate signed by unknown authority: install the CA at/etc/docker/certs.d/registry.example.com/ca.crt; avoidinsecure-registriesoutside a lab.- Large layer rejected or timeouts: a reverse proxy body-size limit (nginx
client_max_body_size) or idle timeout often sits in front of the registry. - Repository not found: some registries, such as Amazon ECR, require creating the repository first.
Production Practice in CI
Automate the push and make it traceable.
- Short-lived credentials: prefer OIDC federation or scoped robot accounts over a personal password in CI.
- Immutable, unique tags: tag with the git SHA or release version; deploy by digest.
- Scan and sign: run an image scanner before promotion and sign with a tool such as cosign if your policy requires it.
- Retention: configure registry lifecycle rules so old CI tags do not grow storage without bound.
- I log in with --password-stdin, tag the image with the registry host and path, and docker push it; the host prefix decides the destination.
- I verify with buildx imagetools inspect and a pull by digest from a clean machine, and give Kubernetes an imagePullSecret.
- In CI I use short-lived credentials, immutable SHA tags, a vulnerability scan before promotion, and lifecycle rules for cleanup.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Tagging as my-app:1.0 and pushing With no host prefix Docker targets Docker Hub, so the push fails or lands in the wrong place.
- Adding the registry to insecure-registries to fix x509 errors It disables TLS verification for that host; install the registry CA under certs.d instead.
- Passing the password with -p on the command line It is visible in shell history and process listings; use --password-stdin.
- Reusing a mutable tag like latest for deployments Nodes can pull different content for the same tag, making rollbacks and audits unreliable.