# kubectl set image: Usage, Options & Common CI Errors

> kubectl set image promotes a Deployment to a new image tag and triggers a rollout. The CI deploy step, container-name mismatches, and the no-diff no-rollout trap.

Source: https://latchkey.dev/learn/command-reference/kubectl-set-image  
Updated: 2026-06-25

Promote a workload to a freshly built image tag in one command.

kubectl set image updates a container's image on a live Deployment and triggers a rolling update. It is the single most common imperative CI deploy step: point a workload at the tag you just built.

## What it does

kubectl set image deploy/NAME container=image:tag patches the named container's image, which Kubernetes treats as a template change and rolls out. You can update multiple containers in one call, and use *=image:tag to set every container at once.

## Common usage

```Terminal
kubectl set image deploy/web web=myreg/web:${GIT_SHA}
kubectl set image deploy/web web=myreg/web:${GIT_SHA} sidecar=myreg/proxy:${GIT_SHA}
kubectl set image deploy/web '*=myreg/web:${GIT_SHA}'
kubectl set image deploy/web web=myreg/web:${GIT_SHA} && \
  kubectl rollout status deploy/web --timeout=180s
```

## Common errors in CI

"error: unable to find container named \"X\"" means the name before the = does not match the Deployment's container name - list it with kubectl get deploy/web -o jsonpath='{.spec.template.spec.containers[*].name}'. The silent CI bug: setting the same tag the Deployment already runs (e.g. re-pushed :latest) is a no-op - Kubernetes sees no spec diff and does NOT roll out, so the "new" image never deploys. Pin to an immutable tag like the commit SHA so every deploy is a real change, and always gate on kubectl rollout status.

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### kubectl set image: Usage, Options & Common CI Errors?

kubectl set image updates a container's image on a live Deployment and triggers a rolling update. It is the single most common imperative CI deploy step: point a workload at the tag you just built.

### What it does?

kubectl set image deploy/NAME container=image:tag patches the named container's image, which Kubernetes treats as a template change and rolls out. You can update multiple containers in one call, and use *=image:tag to set every container at once.

### Common errors in CI?

"error: unable to find container named \"X\"" means the name before the = does not match the Deployment's container name - list it with kubectl get deploy/web -o jsonpath='{.spec.template.spec.containers[*].name}'. The silent CI bug: setting the same tag the Deployment already runs (e.g.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt