Currently, if a local symlink inside the build context points outside of it, Docker silently ignores it and the build fails. The recommended workaround is the named context flag:
docker buildx build --build-context mkdocs=../mkdocs .
COPY --from=mkdocs requirements.txt /app/
This works, but it has a significant limitation: --build-context requires pointing to a directory, not a single file. When you only need one file from an external directory (e.g. a requirements.txt that lives in a shared configuration or dependency file that lives outside the project directory), the entire sibling directory gets transferred to the build daemon — polluting the cache and transferring irrelevant files.
The symlink approach would solve this precisely:
ln -s ../mkdocs/requirements.txt req.txt
docker buildx build --build-context-follow-symlinks .
Only the symlink's target file is transferred. Cache is invalidated only when that specific file changes.
The key argument: these two invocations are functionally identical in terms of what they send to the daemon and what security boundary they cross — the user is explicitly and deliberately referencing files outside the context root in both cases. The only difference is ergonomics.
--build-context-follow-symlinks would be strictly opt-in, so no change in default behavior.
Currently, if a local symlink inside the build context points outside of it, Docker silently ignores it and the build fails. The recommended workaround is the named context flag:
docker buildx build --build-context mkdocs=../mkdocs .COPY --from=mkdocs requirements.txt /app/This works, but it has a significant limitation:
--build-contextrequires pointing to a directory, not a single file. When you only need one file from an external directory (e.g. arequirements.txtthat lives in a shared configuration or dependency file that lives outside the project directory), the entire sibling directory gets transferred to the build daemon — polluting the cache and transferring irrelevant files.The symlink approach would solve this precisely:
ln -s ../mkdocs/requirements.txt req.txt docker buildx build --build-context-follow-symlinks .COPY req.txt /app/Only the symlink's target file is transferred. Cache is invalidated only when that specific file changes.
The key argument: these two invocations are functionally identical in terms of what they send to the daemon and what security boundary they cross — the user is explicitly and deliberately referencing files outside the context root in both cases. The only difference is ergonomics.
--build-context-follow-symlinkswould be strictly opt-in, so no change in default behavior.