# kubectl set image: Command Reference for CI/CD

> Reference for kubectl set image: promote a Deployment to a new image tag in one command, why immutable tags matter, and a CI deploy example.

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

The canonical one-line CI deploy: point a Deployment at a new tag.

kubectl set image updates a container image on a live workload and triggers a rollout. It is the simplest CI deploy step when you build, push, and promote a tag. This reference covers the syntax and the immutable-tag pitfall.

## Common flags and usage

- set image deploy/<name> <container>=<image>:<tag>: update one container
- Use the exact container name from the pod template, not the Deployment name
- Multiple container=image pairs update several at once
- --record (deprecated) historically set change-cause; annotate instead
- Triggers a rollout only if the resulting spec actually changes

## Example

```shell
kubectl set image deploy/web web=myreg/web:${IMAGE_TAG}
kubectl annotate deploy/web \
  kubernetes.io/change-cause="deploy ${GIT_SHA}" --overwrite
kubectl rollout status deploy/web --timeout=180s
```

## In CI

Pin to an immutable tag like the commit SHA. Re-pushing :latest produces an identical spec, so Kubernetes sees no diff and never rolls out the new image. Verify the container name with kubectl get deploy/web -o jsonpath of spec.template.spec.containers, then gate on 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: Command Reference for CI/CD?

kubectl set image updates a container image on a live workload and triggers a rollout. It is the simplest CI deploy step when you build, push, and promote a tag. This reference covers the syntax and the immutable-tag pitfall.

### In CI?

Pin to an immutable tag like the commit SHA. Re-pushing :latest produces an identical spec, so Kubernetes sees no diff and never rolls out the new image. Verify the container name with kubectl get deploy/web -o jsonpath of spec.template.spec.containers, then gate on rollout status.

---

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