# BuildKit HTTPS Git contexts: find the right proxy configuration boundary

> Separate Docker client, build-argument, daemon and BuildKit proxy settings, then isolate HTTPS Git-context retrieval with a controlled docker-container test.

Canonical URL: https://www.devobs.io/articles/diagnose-why-proxy-configuration-does-not-seem-to-be-respected-when-build-efa9b327196fe99f/
By: Maya Chen
Published: 2026-09-11T09:54:15.815Z
Updated: 2026-09-11T09:54:15.815Z
Section: Architecture

Start with **the builder fetching the Git context**, not just the machine running the Docker command. Docker documents remote Git cloning as builder work. With the `docker-container` driver, BuildKit runs in a dedicated container, and `env.KEY` driver options configure that container’s environment. That identifies a boundary to inspect—not a guarantee that a particular Git retrieval will use a proxy. [Build contexts](https://docs.docker.com/build/building/context/#git-repositories), [container driver](https://docs.docker.com/build/builders/drivers/docker-container/)

This distinction matters in BuildKit issue #4643: the reporter already requested proxy variables in the builder container. Recommending those same options without checking their effective values and observing a fresh retrieval does not explain the failure. [Issue #4643](https://github.com/moby/buildkit/issues/4643)

The procedure below separates the configuration surfaces and proposes a controlled `docker-container` experiment. It is not a verified reproduction or fix, and it does not establish a universal BuildKit defect. Its scope is HTTPS Git-context retrieval—not SSH Git access or network requests from Dockerfile `RUN` instructions.

## What the February 2024 report establishes

[Issue #4643](https://github.com/moby/buildkit/issues/4643) was opened on **February 13, 2024**, with the qualified title “Proxy configuration does not seem to be respected with HTTPS Git build contexts.” Its body identifies:

- **Buildx v0.12.1**.
- The **`docker-container`** driver.
- Builder image **`moby/buildkit:v0.12.5`**, with v0.12.5 also appearing in the BuildKit stack trace.
- Builder creation options requesting lowercase `http_proxy` and `https_proxy` environment variables.
- A build invocation supplying uppercase and lowercase HTTP, HTTPS and no-proxy build arguments.
- The reporter’s statement that `github.com` was absent from their `no_proxy` value.

The command also supplied a Git-authentication secret. The anonymous fixture below deliberately removes authentication; it is a minimized diagnostic test, not an exact reproduction of that command.

The failing operation was `[internal] load git source`, followed by an error connecting to the Git host on port 443. The later “failed to read dockerfile” message followed the Git-source failure. Those logs place the reported problem in context retrieval, not a Dockerfile `RUN` instruction. [Reported command and logs](https://github.com/moby/buildkit/issues/4643)

The cited command and logs do not establish the Docker Engine version, resolved proxy values, effective builder environment or independent proxy-access evidence. Several settings were supplied together, so the failure does not isolate their individual effects. It also does not establish a confirmed cause, affected-version range or fixed release.

## A version-labelled proxy-scope matrix

**Reported baseline:** Buildx v0.12.1; BuildKit v0.12.5; `docker-container`; Docker Engine version not established by the cited command and logs. These are reporter-provided observations, not independent test results. [Issue #4643](https://github.com/moby/buildkit/issues/4643)

**Documentation baseline:** Docker’s linked guides are unversioned documentation, not a historical compatibility guarantee for those binaries.

| Configuration surface | Boundary | Documented scope | HTTPS Git-fetch observation in the report |
|---|---|---|---|
| Client `proxies` in `~/.docker/config.json` | Docker client configuration; the guide does not enumerate builder-driver coverage | Configures proxy environment variables for new containers and pre-populates proxy build arguments. It does not configure the Docker CLI’s or Engine’s own proxy. [Client guide](https://docs.docker.com/engine/cli/proxy/) | Client configuration is not documented in the cited command and logs; its presence and individual effect are unknown. |
| Proxy build arguments | Build invocation; `docker-container` in this report | Supplies build-time proxy arguments. The guide does not promise that these configure remote Git-context retrieval. [Client guide](https://docs.docker.com/engine/cli/proxy/) | Supplied alongside builder environment options; the combined attempt failed. Individual effect unknown. |
| Docker daemon proxy configuration | `dockerd`, distinct from a dedicated BuildKit container | Configures daemon proxy behavior, including registry access. [Daemon guide](https://docs.docker.com/engine/daemon/proxy/) | Daemon configuration is not documented in the cited command and logs; its presence and individual effect are unknown. |
| Builder-process environment | Dedicated BuildKit container for `docker-container` | `env.KEY` driver options set environment variables in the container. [Driver guide](https://docs.docker.com/build/builders/drivers/docker-container/) | Lowercase HTTP(S) proxy variables were requested. Effective values were not established; the combined attempt failed. |

A configuration mechanism and an observed connection path are different kinds of evidence. A requested environment variable does not prove that the intended value reached the builder—or that a Git retrieval used it.

## Choose the boundary for your deployment

For **`docker-container`**, inspect the selected BuildKit container’s proxy-related environment. Compare it with the creation options, including uppercase and lowercase names and bypass settings. Docker warns that proxy environment-variable handling is not standardized; do not assume identical interpretation across components. [Driver options](https://docs.docker.com/build/builders/drivers/docker-container/), [proxy-variable caveat](https://docs.docker.com/engine/cli/proxy/)

For **Docker daemon traffic**, use the daemon’s supported configuration mechanism. Docker documents daemon configuration files, flags and startup environment variables, with direct configuration taking precedence over environment variables. That documentation does not establish propagation into a separate BuildKit container. [Daemon proxies](https://docs.docker.com/engine/daemon/proxy/)

Successfully obtaining the builder image is not proof that Git-context retrieval uses the intended proxy. Docker documents image acquisition and submission of the build to the containerized BuildKit server as separate steps. [Driver lifecycle](https://docs.docker.com/build/builders/drivers/docker-container/)

For **Docker Desktop daemon-proxy settings**, Docker says Desktop ignores proxy entries in `daemon.json` and directs users to Desktop settings. Treat that as guidance for the documented Desktop configuration surface, not proof of a separate builder container’s environment or Git-fetch behavior. [Desktop caveat](https://docs.docker.com/engine/daemon/proxy/)

For **another builder driver**, first establish where BuildKit runs and consult that deployment’s version-specific configuration documentation. The `docker-container` options below are not a driver-independent prescription.

## Run a controlled HTTPS Git-context experiment

### 1. Record the deployment without exposing credentials

For each trial, record:

- Docker Engine, Buildx and BuildKit versions.
- Driver, selected builder and node, and BuildKit image identifier where applicable.
- Whether Docker Desktop is involved.
- Client proxy entries, explicit proxy build arguments, daemon settings and effective builder proxy variables as separate fields.
- Relevant shell proxy settings, without assuming they propagate to the builder.
- A run identifier and measurement start and end times.

Include applicable daemon-specific client proxy entries, not just the client’s `default` entry. Docker documents both forms. A daemon-specific entry in the **client** file is still client configuration; it is not the daemon’s own proxy configuration. [Client configuration](https://docs.docker.com/engine/cli/proxy/)

Inspect only necessary fields in a restricted session. Retain sanitized records containing variable names, set/unset status and credential-free endpoint aliases such as `proxy-A`. Do not publish full environment dumps or client configuration files. Docker warns that proxy URLs can contain credentials or sensitive hostnames, and that container environment variables are stored as plain text. Redact credentials, authorization data and sensitive hostnames from diagnostic output before retaining or sharing it. [Proxy security warning](https://docs.docker.com/engine/cli/proxy/)

### 2. Prepare an anonymous repository and local control

Create an anonymously readable HTTPS Git repository you control, with no submodules and only these two tracked files.

`Dockerfile`:

```dockerfile
FROM scratch
COPY marker.txt /marker.txt
```

`marker.txt`:

```text
proxy-probe-001
```

Keep an identical two-file directory at `./probe-local`, outside the repository, as the local-context control. Docker documents both local directories and Git repositories as filesystem contexts from which `COPY` can read files. [Build contexts](https://docs.docker.com/build/building/context/#git-repositories)

The fixture names no external base image and contains no `RUN` instruction or Git credential. Its purpose is to avoid introducing base-image pulls, Dockerfile-step network traffic or authentication into the Git-fetch comparison. Record any unexpected retrieval as a possible confounding input.

Publish the repository before testing, record its default-branch commit and leave it unchanged during each comparison. Use a plain HTTPS Git URL without query parameters or fragments. Docker documents that this form selects the latest commit on the default branch. [Git-context selection](https://docs.docker.com/build/building/context/#git-repositories)

Arrange access to sanitized Git-server transfer records if possible. Without evidence of a new transfer, a successful build alone will not satisfy the freshness check below.

### 3. Establish a baseline and prepare fresh builders

In an isolated test setup, start with no applicable client proxy entries, no explicit proxy build arguments and no builder proxy or bypass variables. Hold daemon configuration, shell settings, network configuration and repository contents constant. The daemon may need its own proxy for setup; record that separately and keep it fixed except in the optional daemon trial.

For an **isolated historical comparison**, this example requests the report’s BuildKit image and adds one builder-environment setting:

```sh
docker buildx create \
  --name proxy-lab-env1 \
  --driver docker-container \
  --driver-opt image=moby/buildkit:v0.12.5 \
  --driver-opt env.https_proxy=http://proxy.example.com:3128 \
  --bootstrap
```

Replace the proxy address with a credential-free lab endpoint. For a current diagnosis, replace the image with the BuildKit version under investigation and record it. Selecting v0.12.5 alone does not reproduce the reported version pair: that also requires Buildx v0.12.1. Docker documents the `image` and `env.KEY` options, and the issue’s creation command uses those mechanisms. [Driver options](https://docs.docker.com/build/builders/drivers/docker-container/), [reported versions](https://github.com/moby/buildkit/issues/4643)

Create the baseline builder under another never-used name, omitting the environment option. Check the selected containers’ actual settings: the baseline should have no unintended proxy or bypass variables, and the environment trial should have only the intended difference.

Use fresh builder state for **each remote-context trial**. Do not import cache or reuse a retained state volume. Docker documents that `docker-container` stores BuildKit state in a dedicated volume and can preserve it across recreation with `--keep-state`; recreating a familiar builder name is not enough to establish freshness. Do not clear a shared production builder’s cache for this experiment. [State persistence](https://docs.docker.com/build/builders/drivers/docker-container/)

Complete bootstrap and builder-image acquisition before measuring Git traffic. If setup fails, record a setup failure—not an HTTPS Git-context result.

### 4. Change one configuration setting at a time

Prepare fresh state for each comparison and change only the designated setting:

| Trial | Change from baseline | Isolation check |
|---|---|---|
| Baseline | None | Record effective settings and evidence of a fresh retrieval attempt. |
| Client | Add only the applicable client `httpsProxy` key after creating and bootstrapping the trial’s builder | Record the derived proxy arguments where observable; verify that the existing builder environment remains unchanged. |
| Build argument | Add only `--build-arg HTTPS_PROXY=http://proxy.example.com:3128` to the build command | Keep builder environment and client configuration unchanged. Test lowercase spelling separately. |
| Builder environment | Add only `env.https_proxy=http://proxy.example.com:3128` when creating the trial’s builder | Verify the intended value is present in the selected BuildKit container. |
| Daemon, if applicable | Change only the supported daemon HTTPS proxy setting | Use an isolated Engine deployment, keep builder environment fixed and complete any required setup before measurement. |

One changed configuration key can produce multiple derived settings. Docker maps client `httpsProxy` to both uppercase and lowercase variables or arguments. Its guide also says client proxy changes apply to new containers and builds, not existing containers. Record those distinctions rather than calling the client trial a single-environment-variable test. [Client proxy mapping and scope](https://docs.docker.com/engine/cli/proxy/)

If another relevant setting changes, mark the comparison as confounded. Before a daemon trial, verify configuration support for the tested Engine version. Docker’s daemon guide requires a restart after changing its configuration file; do not restart a shared daemon to complete this matrix. [Daemon configuration](https://docs.docker.com/engine/daemon/proxy/)

### 5. Run the local and HTTPS contexts

Explicitly select the trial builder and use distinct output tags:

```sh
docker buildx build \
  --builder proxy-lab-env1 \
  --progress=plain \
  --load \
  -t proxy-probe:env1-local \
  ./probe-local

docker buildx build \
  --builder proxy-lab-env1 \
  --progress=plain \
  --load \
  -t proxy-probe:env1-git \
  https://git.example.com/proxy-probe.git
```

Replace the Git URL with your anonymous repository. Substitute the appropriate builder and tags for each trial; add the designated build argument only in its trial.

Docker documents local paths and remote Git URLs as context inputs. The driver guide documents explicit builder selection and `--load` for loading the result into Docker rather than leaving it only in the build cache. [Context inputs](https://docs.docker.com/build/building/context/#git-repositories), [builder selection and output](https://docs.docker.com/build/builders/drivers/docker-container/)

Use your image-inspection tooling to verify that `/marker.txt` contains the expected marker. Do not add a networked `RUN` step for this check. A correct marker is an output check—not proof of a fresh Git transfer or proxy use.

### 6. Establish freshness and proxy use separately

**Do not treat `--no-cache` alone as proof of a new Git fetch.** For this experiment, require independent observations:

- Record the source-loading operation and measurement window in sanitized build output.
- Correlate sanitized proxy access records with the builder’s traffic, Git hostname and time window.
- Before calling a retrieval a completed fresh fetch, obtain Git-server evidence of a transfer during that window and verify the expected output marker.
- For a failure, distinguish an observed connection attempt from a completed transfer. If an attempt is not independently established, say so.
- Validate proxy logging with a separate known-proxied lab request before measuring. Missing entries in unvalidated logs do not establish bypass.

If the evidence is unavailable, label freshness or proxy use **unverified** rather than inferring it from build success.

Keep a version-labelled results ledger:

`run ID | Engine/Buildx/BuildKit | driver/node | changed setting | effective sanitized configuration | local result | Git result | freshness evidence | proxy evidence`

## Interpret the result without overstating it

- **Local context succeeds; HTTPS context fails:** investigate the remote-context path. The contrast does not identify a proxy root cause.
- **A matching request reaches the proxy, then fails:** investigate that failure rather than saying the proxy was simply ignored. A proxy entry does not prove a completed Git transfer.
- **No matching proxy request appears:** verify logging, a fresh retrieval attempt, the selected builder and its effective settings before drawing a routing conclusion.
- **Only the builder-environment trial succeeds:** repeat the comparison and report the exact versions, driver and observations. Do not generalize the result to every BuildKit deployment.
- **The intended environment is present but retrieval still fails:** preserve the minimized reproduction and investigate the observed connection path. The original report already requested builder environment variables; repeating that request is not a diagnosis. [Issue #4643](https://github.com/moby/buildkit/issues/4643)

If changing only BuildKit or Buildx version changes the outcome, document that controlled difference. Describe a release as a confirmed fix only when primary evidence—such as maintainer findings, release documentation or a regression test—supports the conclusion.

The practical sequence is: **identify who fetches the context, verify the configuration that component received, establish a fresh retrieval attempt, and observe where the traffic went.** That separates a configuration-boundary mistake from an unresolved, version-specific Git-fetch problem without turning one report into a universal defect.

## Source references

- <https://docs.docker.com/build/building/context/#git-repositories>
- <https://docs.docker.com/engine/cli/proxy/>
- <https://docs.docker.com/build/builders/drivers/docker-container/>
- <https://docs.docker.com/engine/daemon/proxy/>
- <https://github.com/moby/buildkit/issues/4643>