What is a Docker credential helper (a `docker-credential-*` binary), and why do cloud registries such as Amazon ECR effectively require one instead of a one-off `docker login`?

## The default and why it is weak `docker login registry.example.com` writes into `~/.docker/config.json`: ```json {"auths":{"registry.example.com":{"auth":"Y2ktYm90OnMzY3JldA=="}}} ``` That `auth` value is `base64(username:password)` — encoding, not encryption. Anyone who can read the file, or any process running as that user, recovers the password. The credential is also long-lived and identical everywhere it is copied, which is exactly what you do not want on a fleet of build agents. ## The helper protocol A credential helper is any executable named `docker-credential-<name>` on `PATH` that speaks a tiny line protocol: - `get` — reads a registry URL on stdin, writes `{"ServerURL":"...","Username":"...","Secret":"..."}` on stdout. - `store` — reads that same JSON on stdin and persists it (used by `docker login`). - `erase` — reads a URL and deletes the entry (used by `docker logout`). You wire it up in `~/.docker/config.json` two ways: ```json { "credsStore": "osxkeychain", "credHelpers": { "111122223333.dkr.ecr.eu-west-1.amazonaws.com": "ecr-login", "europe-docker.pkg.dev": "gcloud" } } ``` `credsStore` is the default for all registries; `credHelpers` overrides it per host and wins. With either in place, the `auths` entry holds no secret — often just an empty object — and the CLI shells out on every request. ## Two different problems being solved **Problem 1: secrets at rest.** `osxkeychain`, `wincred`, `pass` and `secretservice` keep the *same* credential but delegate storage to the OS keychain or a GPG-backed store. The threat model addressed is a readable dotfile, a backup, or a `COPY . .` that sweeps the config into an image layer. **Problem 2: credentials that expire and should not exist.** Cloud registries authenticate you with an *ambient identity*, not a registry password: - **Amazon ECR** — `aws ecr get-login-password` calls `ecr:GetAuthorizationToken` with your IAM identity and returns a password valid for **12 hours**, used with the literal username `AWS`. `docker-credential-ecr-login` performs that call transparently on every registry request, resolving IAM credentials from the instance/task role, environment, or profile. Nothing is stored, and there is no daily re-login cron. - **Google Artifact Registry / GCR** — `gcloud auth configure-docker` installs the `gcloud` helper, which exchanges the active service-account or workload identity for an OAuth access token per call. - **Azure Container Registry** — the ACR helper exchanges an Entra token for an ACR refresh token. The payoff: the machine's identity *is* the credential. Rotation is automatic, revocation is a policy change rather than a secret-rotation exercise, and no long-lived registry password exists to leak. ## Operational notes worth saying out loud - **The helper must be on `PATH` for the user that runs the CLI.** A helper installed for your shell but missing for the CI user produces `error getting credentials - err: exec: "docker-credential-ecr-login": executable file not found`. - **Helpers serve the CLI, not other runtimes.** The Docker daemon receives credentials passed by the CLI on the pull request. Other consumers — containerd, other build tools, orchestrators — have their own credential configuration and do not read your `config.json`. Orchestrator-side image pull credentials are a separate mechanism. - **`docker login` still works with a helper configured**; it routes to `store` instead of writing the base64 blob. With identity-derived helpers, an explicit login is simply unnecessary. - **Per-host mapping must match exactly.** The key in `credHelpers` is the registry host as it appears in image references, including the account ID and region for ECR. - **Failure mode is quiet.** If the helper cannot resolve an identity (expired SSO session, no instance role), it returns an error the CLI reports as a credential problem, which is easy to mistake for a permissions problem. Running the helper by hand — `echo <host> | docker-credential-ecr-login get` — separates the two in seconds. ## When a plain login is still fine Short-lived contexts with a scoped, disposable token — an ephemeral CI job that logs in with a job-scoped token and exits — do not need a helper. The helper earns its place on long-lived machines, on developer laptops, and anywhere the alternative is a static password copied around.