From 2726a4037e6d4f64d85db451ec9805decfe954e9 Mon Sep 17 00:00:00 2001 From: Akihiro Suda Date: Fri, 29 Aug 2025 15:25:22 +0900 Subject: [PATCH 1/3] build: document URL queries BuildKit v0.24 introduces URL like `https://github.com/example/example.git?tag=v0.0.1&checksum=deadbeef` See moby/buildkit PR 6172 Signed-off-by: Akihiro Suda --- content/manuals/build/concepts/context.md | 28 +++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/content/manuals/build/concepts/context.md b/content/manuals/build/concepts/context.md index 2bff1f4eef68..0c54b7284f3d 100644 --- a/content/manuals/build/concepts/context.md +++ b/content/manuals/build/concepts/context.md @@ -245,6 +245,34 @@ docker build github.com/docker/buildx#d4f088e689b41353d74f1a0bfcd6d7c0b213aed2 docker build github.com/docker/buildx#d4f088e ``` +### URL queries + +Starting with Buildx v0.28 and BuildKit v0.24, URL queries are also supported. +URL queries are more structured and recommended over [URL fragments](#url-fragments). + +For example, +```console +$ docker buildx build 'https://github.com/user/myrepo.git?branch=container&subdir=docker' +``` + +| Build Syntax Suffix | Commit Used | Build Context Used | +| -------------------------------------------- | ----------------------------- | ------------------ | +| `myrepo.git` | `refs/heads/` | `/` | +| `myrepo.git?tag=mytag` | `refs/tags/mytag` | `/` | +| `myrepo.git?branch=mybranch` | `refs/heads/mybranch` | `/` | +| `myrepo.git?ref=pull/42/head` | `refs/pull/42/head` | `/` | +| `myrepo.git?subdir=myfolder` | `refs/heads/` | `/myfolder` | +| `myrepo.git?branch=master&subdir=myfolder` | `refs/heads/master` | `/myfolder` | +| `myrepo.git?tag=mytag&subdir=myfolder` | `refs/tags/mytag` | `/myfolder` | +| `myrepo.git?branch=mybranch&subdir=myfolder` | `refs/heads/mybranch` | `/myfolder` | + +A commit hash can be specified as a `commit` or `checksum` query, along with `tag`, `branch`, or `ref`. +A hash does not need to be a full hash. + +```bash +docker buildx build 'https://github.com/moby/buildkit.git?tag=v0.21.1&checksum=66735c67' +``` + #### Keep `.git` directory By default, BuildKit doesn't keep the `.git` directory when using Git contexts. From 21d704443afbbcc5493ba58ba62c77a8b77a1a78 Mon Sep 17 00:00:00 2001 From: CrazyMax <1951866+crazy-max@users.noreply.github.com> Date: Wed, 3 Sep 2025 16:49:44 +0200 Subject: [PATCH 2/3] build: update git url queries behavior Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com> --- content/manuals/build/concepts/context.md | 31 +++++++++++++++++------ 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/content/manuals/build/concepts/context.md b/content/manuals/build/concepts/context.md index 0c54b7284f3d..ad319a0a8fd5 100644 --- a/content/manuals/build/concepts/context.md +++ b/content/manuals/build/concepts/context.md @@ -245,12 +245,11 @@ docker build github.com/docker/buildx#d4f088e689b41353d74f1a0bfcd6d7c0b213aed2 docker build github.com/docker/buildx#d4f088e ``` -### URL queries +#### URL queries -Starting with Buildx v0.28 and BuildKit v0.24, URL queries are also supported. -URL queries are more structured and recommended over [URL fragments](#url-fragments). +Starting with Buildx v0.28, BuildKit v0.24 and Dockerfile v1.18, URL queries are +also supported. URL queries are more structured and recommended over [URL fragments](#url-fragments): -For example, ```console $ docker buildx build 'https://github.com/user/myrepo.git?branch=container&subdir=docker' ``` @@ -266,13 +265,29 @@ $ docker buildx build 'https://github.com/user/myrepo.git?branch=container&subdi | `myrepo.git?tag=mytag&subdir=myfolder` | `refs/tags/mytag` | `/myfolder` | | `myrepo.git?branch=mybranch&subdir=myfolder` | `refs/heads/mybranch` | `/myfolder` | -A commit hash can be specified as a `commit` or `checksum` query, along with `tag`, `branch`, or `ref`. -A hash does not need to be a full hash. +A commit hash can be specified as a `checksum` (alias `commit`) query, along +`tag`, `branch`, or `ref` queries to verify that the reference resolves to the +expected commit: -```bash -docker buildx build 'https://github.com/moby/buildkit.git?tag=v0.21.1&checksum=66735c67' +```console +$ docker buildx build 'https://github.com/moby/buildkit.git?tag=v0.21.1&checksum=66735c67' +``` + +If it doesn't match, the build fails: + +```console +$ docker buildx build 'https://github.com/user/myrepo.git?tag=v0.1.0&commit=deadbeef' +... +#3 [internal] load git source https://github.com/user/myrepo.git?tag=v0.1.0-rc1&commit=deadbeef +#3 0.484 bb41e835b6c3523c7c45b248cf4b45e7f862bc42 refs/tags/v0.1.0 +#3 ERROR: expected checksum to match deadbeef, got bb41e835b6c3523c7c45b248cf4b45e7f862bc42 ``` +> [!NOTE] +> +> Short commit hash is supported with `checksum` (alias `commit`) query but for +> `ref`, only the full hash of the commit is supported. + #### Keep `.git` directory By default, BuildKit doesn't keep the `.git` directory when using Git contexts. From 7084e318831236dcd4cf27f241a3beb30a905509 Mon Sep 17 00:00:00 2001 From: Allie Sadler <102604716+aevesdocker@users.noreply.github.com> Date: Thu, 4 Sep 2025 09:58:13 +0100 Subject: [PATCH 3/3] Apply suggestions from code review --- content/manuals/build/concepts/context.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/build/concepts/context.md b/content/manuals/build/concepts/context.md index ad319a0a8fd5..c5b1c0e92c96 100644 --- a/content/manuals/build/concepts/context.md +++ b/content/manuals/build/concepts/context.md @@ -254,7 +254,7 @@ also supported. URL queries are more structured and recommended over [URL fragme $ docker buildx build 'https://github.com/user/myrepo.git?branch=container&subdir=docker' ``` -| Build Syntax Suffix | Commit Used | Build Context Used | +| Build syntax suffix | Commit used | Build context used | | -------------------------------------------- | ----------------------------- | ------------------ | | `myrepo.git` | `refs/heads/` | `/` | | `myrepo.git?tag=mytag` | `refs/tags/mytag` | `/` | @@ -265,7 +265,7 @@ $ docker buildx build 'https://github.com/user/myrepo.git?branch=container&subdi | `myrepo.git?tag=mytag&subdir=myfolder` | `refs/tags/mytag` | `/myfolder` | | `myrepo.git?branch=mybranch&subdir=myfolder` | `refs/heads/mybranch` | `/myfolder` | -A commit hash can be specified as a `checksum` (alias `commit`) query, along +A commit hash can be specified as a `checksum` (alias `commit`) query, along with `tag`, `branch`, or `ref` queries to verify that the reference resolves to the expected commit: