Docker

The recommended image to run is alpine, as they are the smallest Docker images we provide. This will execute GitVersion for the current working directory ($(pwd)) on Linux and Unix or powershell on Windows:

docker run --rm -v "$(pwd):/repo" gittools/gitversion:{tag} /repo

The following command will execute GitVersion for the current working directory (%CD%) on Windows with CMD:

docker run --rm -v "%CD%:/repo" gittools/gitversion:{tag} /repo

Note that the path /repo needs to be passed as an argument since the gitversion executable within the container is not aware of the fact that it's running inside a container.

In v7, images run as UID/GID 10001:10001. These commands require the mounted repository to be writable by that user. On Linux, you may need to add --user "$(id -u):$(id -g)" when running from the non-root checkout owner's shell. See repository permissions for details.

CI Agents

If you are running GitVersion on a CI agent, you may need to specify environment variables to allow GitVersion to work correctly. The following examples use a POSIX shell on a Linux agent running as the non-root checkout owner. They pass that user's UID/GID so GitVersion can write to the mounted checkout.

For example, on Azure DevOps:

docker run --rm --user "$(id -u):$(id -g)" -v "$(pwd):/repo" \
  --env TF_BUILD=true --env BUILD_SOURCEBRANCH="$BUILD_SOURCEBRANCH" \
  gittools/gitversion:{tag} /repo

On GitHub Actions, you may need to set the following environment variables:

docker run --rm --user "$(id -u):$(id -g)" -v "$(pwd):/repo" \
  --env GITHUB_ACTIONS=true --env GITHUB_REF="$GITHUB_REF" \
  gittools/gitversion:{tag} /repo

Non-root containers and repository permissions

GitVersion v7 images default to UID/GID 10001:10001, with a writable home at /home/gittools. The usual command needs no extra flags when that user can write to the mounted repository. GitVersion can write repository metadata and cache files, so bind mounts must be writable by the selected user. On Linux, use the non-root checkout owner's identity:

docker run --rm --user "$(id -u):$(id -g)" \
  -v "$(pwd):/repo" gittools/gitversion:{tag} /repo

The image automatically creates a private temporary home if the selected user cannot write to the configured home. No HOME or DOTNET_CLI_HOME flags are needed, and the temporary home stays inside the disposable container. Do not run this command from a root shell, or make the host repository world-writable to bypass permissions. For Docker Desktop on Windows/macOS, ensure the shared directory is writable by the image's default user using the host's file-sharing permissions.

Derived images can switch to root during installation, but must restore USER 10001:10001 for runtime. The tool remains installed at /tools/dotnet-gitversion.

Tags

Most of the tags we provide have both arm64 and amd64 variants. If you need to pull a architecture specific tag you can do that like:

docker run --rm -v "$(pwd):/repo" gittools/gitversion:{tag}-amd64 /repo
docker run --rm -v "$(pwd):/repo" gittools/gitversion:{tag}-arm64 /repo

The list of available containers can be found on Docker Hub.

Explore GitVersion on Docker Hub