# kubectl rollout history: Usage, Options & Common CI Errors

> kubectl rollout history lists a Deployment's revisions and their change-cause. Inspecting a specific revision, the revision-history limit, and CI gotchas.

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

See every revision of a Deployment and what changed.

kubectl rollout history lists the revisions a Deployment, StatefulSet, or DaemonSet has gone through, so you can pick a target to roll back to. In CI it is how you confirm a deploy actually produced a new revision.

## What it does

kubectl rollout history deploy/NAME prints the revision numbers and their CHANGE-CAUSE annotation. Add --revision=N to dump the full pod template for one revision so you can diff what that rollout shipped. The number of revisions kept is bounded by spec.revisionHistoryLimit (default 10).

## Common usage

```Terminal
kubectl rollout history deploy/web
kubectl rollout history deploy/web --revision=3
kubectl rollout history statefulset/db
kubectl annotate deploy/web kubernetes.io/change-cause="deploy ${GIT_SHA}"
```

## Common errors in CI

A CHANGE-CAUSE column showing only "<none>" is the usual surprise: the cause is populated from the kubernetes.io/change-cause annotation, which is no longer set automatically - set it yourself on every deploy so history is meaningful. "error: unable to find specified revision N in history" means that revision aged out past revisionHistoryLimit, so you cannot roll back to it; raise the limit if you need a deeper window. Remember a re-applied identical spec does not create a new revision, so history will not grow on a no-op deploy.

## 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 rollout history: Usage, Options & Common CI Errors?

kubectl rollout history lists the revisions a Deployment, StatefulSet, or DaemonSet has gone through, so you can pick a target to roll back to. In CI it is how you confirm a deploy actually produced a new revision.

### What it does?

kubectl rollout history deploy/NAME prints the revision numbers and their CHANGE-CAUSE annotation. Add --revision=N to dump the full pod template for one revision so you can diff what that rollout shipped. The number of revisions kept is bounded by spec.revisionHistoryLimit (default 10).

### Common errors in CI?

A CHANGE-CAUSE column showing only "<none>" is the usual surprise: the cause is populated from the kubernetes.io/change-cause annotation, which is no longer set automatically - set it yourself on every deploy so history is meaningful.

---

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