5.1.1.3 Git Build Context

A Git build context allows docker build to use a remote Git repository URL directly as its build context, cloning the repository and using its contents (at a specified branch, tag, or commit) without requiring a local checkout to already exist.

Basic Usage

Supplying a Git URL in place of a local path tells Docker to clone that repository and use its contents as the build context.

docker build -t myapp https://github.com/example/myapp.git

Docker clones this repository internally and builds directly from its contents, without requiring the repository to already exist locally.

Specifying a Branch, Tag, or Subdirectory

A specific reference and an optional subdirectory within the repository can both be specified as part of the same URL.

docker build -t myapp https://github.com/example/myapp.git#release-2.0

docker build -t myapp https://github.com/example/myapp.git#main:backend

The second example builds specifically from the backend subdirectory of the main branch, rather than the repository's root.

Why a Git Context Can Be Useful

Building directly from a Git URL is useful for CI systems or automation that need to trigger a build of a specific, exact commit or tag, without needing to manage a separate local clone step beforehand.

docker build -t myapp:release-2.0 https://github.com/example/myapp.git#release-2.0

Limitations Compared to a Local Directory Context

A Git context only includes what is actually committed to the repository — any local, uncommitted changes are simply not available to a build using this method, which can be surprising if expecting the build to reflect a local working directory's current state.

git status
docker build -t myapp https://github.com/example/myapp.git

Uncommitted local changes shown by git status have no effect on this build at all, since the build clones a fresh copy from the remote repository rather than using any local working directory.

Why Git Build Context Matters

Building directly from a Git reference provides a clean, reproducible way to build an image from an exact, known repository state, which is particularly valuable in automated pipelines that need strong guarantees about exactly which source the resulting image reflects.