# kubectl annotate: Command Reference for CI/CD

> Reference for kubectl annotate: attach non-identifying metadata to resources, the change-cause annotation for rollout history, the size cap, and a CI example.

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

Attach metadata that tools read but selectors ignore.

kubectl annotate sets free-form key/value metadata that controllers and tooling read but selectors never match. Its headline CI use is the change-cause annotation that makes rollout history meaningful. This reference covers the syntax and limits.

## Common flags and usage

- annotate <res> <name> k=v: add an annotation
- annotate <res> <name> k-: remove an annotation
- --overwrite: replace an existing annotation (required for re-runs)
- -l / --all: annotate many objects at once
- No value-format rules, but a 256 KB total payload cap

## Example

```shell
kubectl annotate deploy/web \
  kubernetes.io/change-cause="deploy ${GIT_SHA}" --overwrite
kubectl annotate svc/web prometheus.io/scrape="true" --overwrite
```

## In CI

Set change-cause on each deploy so kubectl rollout history shows which revision was what. Like label, re-running without --overwrite fails. The annotations payload is capped at 256 KB; client-side apply stores last-applied-configuration there, so very large manifests should use --server-side apply.

## 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 annotate: Command Reference for CI/CD?

kubectl annotate sets free-form key/value metadata that controllers and tooling read but selectors never match. Its headline CI use is the change-cause annotation that makes rollout history meaningful. This reference covers the syntax and limits.

### In CI?

Set change-cause on each deploy so kubectl rollout history shows which revision was what. Like label, re-running without --overwrite fails. The annotations payload is capped at 256 KB; client-side apply stores last-applied-configuration there, so very large manifests should use --server-side apply.

---

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