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

[DhananjayPurohit]

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