Support custom HTTP headers on `docker pull` / `docker push` (parity with ORAS and git)

Start by tracing the docker pull and docker push command entry points into the daemon's registry requests, then compare how ORAS and git handle repeatable headers. Done means both commands accept -H/--header repeatedly, pass those headers to registry requests, preserve current behavior without the flag, and define handling for reserved headers.

Description

Summary

Add a repeatable --header / -H "Key: Value" flag to docker pull and docker push that attaches user-supplied HTTP headers to the registry requests the daemon makes. This brings the docker CLI to parity with tooling that already supports it (ORAS, git).

Motivation

Today the only header a client can influence on a pull/push is the credential from docker login (Basic or Bearer). That is not enough for a growing set of real setups:

• Parity with ORAS. oras pull, oras push, and oras cp already support --header, and it is widely used for custom registry and gateway integrations. Users who need a header today are pushed off the docker CLI onto ORAS or bespoke clients, losing docker daemon integration.
• Custom auth proxies / gateways. Registries fronted by a proxy that expects a header other than Basic/Bearer — an API-key header, a signed token, a tenant or region selector — cannot be used with plain docker pull. docker login can only express the standard credential.
• Header-based routing / multi-tenancy. A gateway that routes or scopes based on a custom header (e.g. X-Tenant) has no way to receive it from docker.
• Observability in CI. Passing correlation/trace headers (X-Request-ID, traceparent) through pulls to debug slow or failing registry paths.
• Experimenting with registry extensions. Custom registries trying out new capabilities need a header channel without asking every user to fork the CLI.

Prior art

This is well precedented:

• ORAS --header / -H (same ecosystem, OCI registries).
• git http.extraHeader (git -c http.extraHeader="Key: Value" clone …) — added for exactly these proxy/auth scenarios.
• curl -H.

Proposed UX

docker pull  -H "X-Example: value" [-H "X-Other: value"] registry/name:tag
docker push  -H "X-Example: value" registry/name:tag

Repeatable; headers applied to the registry requests for that command. Reserved headers (e.g. Authorization, Host) could be rejected or gated to avoid surprising interactions with existing auth.

Alternatives considered

• Credential helpers — only cover authentication, not arbitrary headers.
• ORAS — works, but does not load images into the docker daemon.
• Forking the CLI — impractical for end users.

Compatibility

Fully opt-in and backward compatible: no --header means no change