From 3123dce06884167dfe12332f10e5431754769a15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jan=20Christian=20Gr=C3=BCnhage?= Date: Thu, 25 Sep 2025 17:52:08 +0200 Subject: [PATCH 1/8] build: git remote authentication secrets --- content/manuals/build/building/secrets.md | 69 ++++++++++++++--------- 1 file changed, 43 insertions(+), 26 deletions(-) diff --git a/content/manuals/build/building/secrets.md b/content/manuals/build/building/secrets.md index b262d39e4603..41889f557659 100644 --- a/content/manuals/build/building/secrets.md +++ b/content/manuals/build/building/secrets.md @@ -175,29 +175,29 @@ building with remote, private Git repositories, including: - Building with a private Git repository as build context - Fetching private Git repositories in a build with `ADD` -For example, say you have a private GitLab project at -`https://gitlab.com/example/todo-app.git`, and you want to run a build using +For example, say you have a private GitHub repository at +`https://github.com/example/todo-app.git`, and you want to run a build using that repository as the build context. An unauthenticated `docker build` command fails because the builder isn't authorized to pull the repository: ```console -$ docker build https://gitlab.com/example/todo-app.git +$ docker build https://github.com/example/todo-app.git [+] Building 0.4s (1/1) FINISHED - => ERROR [internal] load git source https://gitlab.com/example/todo-app.git + => ERROR [internal] load git source https://github.com/example/todo-app.git ------ - > [internal] load git source https://gitlab.com/example/todo-app.git: -0.313 fatal: could not read Username for 'https://gitlab.com': terminal prompts disabled + > [internal] load git source https://github.com/example/todo-app.git: +0.313 fatal: could not read Username for 'https://github.com': terminal prompts disabled ------ ``` -To authenticate the builder to the Git server, set the `GIT_AUTH_TOKEN` -environment variable to contain a valid GitLab access token, and pass it as a +To authenticate the builder to GitHub, set the `GIT_AUTH_TOKEN` +environment variable to contain a valid GitHub access token, and pass it as a secret to the build: ```console -$ GIT_AUTH_TOKEN=$(cat gitlab-token.txt) docker build \ +$ GIT_AUTH_TOKEN=$(gh auth token) docker build \ --secret id=GIT_AUTH_TOKEN \ - https://gitlab.com/example/todo-app.git + https://github.com/example/todo-app.git ``` The `GIT_AUTH_TOKEN` also works with `ADD` to fetch private Git repositories as @@ -205,31 +205,50 @@ part of your build: ```dockerfile FROM alpine -ADD https://gitlab.com/example/todo-app.git /src +ADD https://github.com/example/todo-app.git /src ``` ### HTTP authentication scheme -By default, Git authentication over HTTP uses the Bearer authentication scheme: +BuildKit supports two types of Git authentication secrets, and you should use either one or the other, not both: + +- **`GIT_AUTH_TOKEN`**: Uses Basic authentication with a fixed username of `x-access-token` (GitHub-specific) +- **`GIT_AUTH_HEADER`**: Uses the raw authorization header value you provide (works with any Git provider) + +#### Using GIT_AUTH_TOKEN (f.ex. GitHub) + +When you use `GIT_AUTH_TOKEN`, BuildKit automatically constructs a Basic authentication header using `x-access-token` as the user: ```http -Authorization: Bearer +Authorization: Basic ")> ``` -If you need to use a Basic scheme, with a username and password, you can set -the `GIT_AUTH_HEADER` build secret: +This method works with GitHub. Example usage: ```console -$ export GIT_AUTH_TOKEN=$(cat gitlab-token.txt) -$ export GIT_AUTH_HEADER=basic +$ export GIT_AUTH_TOKEN=$(gh auth token) $ docker build \ --secret id=GIT_AUTH_TOKEN \ + https://github.com/example/todo-app.git +``` + +#### Using GIT_AUTH_HEADER (Any Git provider) + +When you use `GIT_AUTH_HEADER`, BuildKit uses the exact value you provide as the authorization header: + +```http +Authorization: +``` + +Example usage with GitLab CI/CD token: + +```console +$ export GIT_AUTH_HEADER="Basic $(echo -n "gitlab-ci-token:${CI_JOB_TOKEN}" | base64)" +$ docker build \ --secret id=GIT_AUTH_HEADER \ https://gitlab.com/example/todo-app.git ``` -BuildKit currently only supports the Bearer and Basic schemes. - ### Multiple hosts You can set the `GIT_AUTH_TOKEN` and `GIT_AUTH_HEADER` secrets on a per-host @@ -238,12 +257,10 @@ hostnames. To specify a hostname, append the hostname as a suffix to the secret ID: ```console -$ export GITLAB_TOKEN=$(cat gitlab-token.txt) -$ export GERRIT_TOKEN=$(cat gerrit-username-password.txt) -$ export GERRIT_SCHEME=basic +$ export GITHUB_TOKEN=$(gh auth token) +$ export GITLAB_AUTH_HEADER="Basic $(echo -n "gitlab-ci-token:${CI_JOB_TOKEN}" | base64)" $ docker build \ - --secret id=GIT_AUTH_TOKEN.gitlab.com,env=GITLAB_TOKEN \ - --secret id=GIT_AUTH_TOKEN.gerrit.internal.example,env=GERRIT_TOKEN \ - --secret id=GIT_AUTH_HEADER.gerrit.internal.example,env=GERRIT_SCHEME \ - https://gitlab.com/example/todo-app.git + --secret id=GIT_AUTH_TOKEN.github.com,env=GITHUB_TOKEN \ + --secret id=GIT_AUTH_HEADER.gitlab.com,env=GITLAB_AUTH_HEADER \ + https://github.com/example/todo-app.git ``` From 6346a6c243264267d8ce39a8c355685b88089edc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?JC=20Gr=C3=BCnhage?= Date: Fri, 24 Apr 2026 10:32:19 +0200 Subject: [PATCH 2/8] Update content/manuals/build/building/secrets.md Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/build/building/secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/building/secrets.md b/content/manuals/build/building/secrets.md index 41889f557659..6428a0b7510e 100644 --- a/content/manuals/build/building/secrets.md +++ b/content/manuals/build/building/secrets.md @@ -210,7 +210,7 @@ ADD https://github.com/example/todo-app.git /src ### HTTP authentication scheme -BuildKit supports two types of Git authentication secrets, and you should use either one or the other, not both: +BuildKit supports two Git authentication secrets: - **`GIT_AUTH_TOKEN`**: Uses Basic authentication with a fixed username of `x-access-token` (GitHub-specific) - **`GIT_AUTH_HEADER`**: Uses the raw authorization header value you provide (works with any Git provider) From c50c393d6139a66a8536b1cfea8a4e713e177515 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?JC=20Gr=C3=BCnhage?= Date: Fri, 24 Apr 2026 10:32:37 +0200 Subject: [PATCH 3/8] Update content/manuals/build/building/secrets.md Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/build/building/secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/building/secrets.md b/content/manuals/build/building/secrets.md index 6428a0b7510e..daa89cf6a4dc 100644 --- a/content/manuals/build/building/secrets.md +++ b/content/manuals/build/building/secrets.md @@ -212,7 +212,7 @@ ADD https://github.com/example/todo-app.git /src BuildKit supports two Git authentication secrets: -- **`GIT_AUTH_TOKEN`**: Uses Basic authentication with a fixed username of `x-access-token` (GitHub-specific) +- **`GIT_AUTH_TOKEN`**: Uses Basic authentication with a fixed username of `x-access-token` (the GitHub-style default) - **`GIT_AUTH_HEADER`**: Uses the raw authorization header value you provide (works with any Git provider) #### Using GIT_AUTH_TOKEN (f.ex. GitHub) From dacd76a697963be7f388a18dbb3a6e2a09d83434 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?JC=20Gr=C3=BCnhage?= Date: Fri, 24 Apr 2026 10:32:53 +0200 Subject: [PATCH 4/8] Update content/manuals/build/building/secrets.md Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/build/building/secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/building/secrets.md b/content/manuals/build/building/secrets.md index daa89cf6a4dc..3d75dc149137 100644 --- a/content/manuals/build/building/secrets.md +++ b/content/manuals/build/building/secrets.md @@ -215,7 +215,7 @@ BuildKit supports two Git authentication secrets: - **`GIT_AUTH_TOKEN`**: Uses Basic authentication with a fixed username of `x-access-token` (the GitHub-style default) - **`GIT_AUTH_HEADER`**: Uses the raw authorization header value you provide (works with any Git provider) -#### Using GIT_AUTH_TOKEN (f.ex. GitHub) +#### Using GIT_AUTH_TOKEN (for example, GitHub) When you use `GIT_AUTH_TOKEN`, BuildKit automatically constructs a Basic authentication header using `x-access-token` as the user: From c950a93ae669c6c13d2eb53a6137532c8a7f3e29 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?JC=20Gr=C3=BCnhage?= Date: Fri, 24 Apr 2026 10:33:02 +0200 Subject: [PATCH 5/8] Update content/manuals/build/building/secrets.md Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/build/building/secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/building/secrets.md b/content/manuals/build/building/secrets.md index 3d75dc149137..603d59f5034d 100644 --- a/content/manuals/build/building/secrets.md +++ b/content/manuals/build/building/secrets.md @@ -217,7 +217,7 @@ BuildKit supports two Git authentication secrets: #### Using GIT_AUTH_TOKEN (for example, GitHub) -When you use `GIT_AUTH_TOKEN`, BuildKit automatically constructs a Basic authentication header using `x-access-token` as the user: +When you use `GIT_AUTH_TOKEN`, BuildKit constructs a Basic authentication header using `x-access-token` as the user: ```http Authorization: Basic ")> From ff60f225cdb123545d940e7785f4dfa1b064eb59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?JC=20Gr=C3=BCnhage?= Date: Fri, 24 Apr 2026 10:33:16 +0200 Subject: [PATCH 6/8] Update content/manuals/build/building/secrets.md Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/build/building/secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/building/secrets.md b/content/manuals/build/building/secrets.md index 603d59f5034d..e2e571b2ae87 100644 --- a/content/manuals/build/building/secrets.md +++ b/content/manuals/build/building/secrets.md @@ -223,7 +223,7 @@ When you use `GIT_AUTH_TOKEN`, BuildKit constructs a Basic authentication header Authorization: Basic ")> ``` -This method works with GitHub. Example usage: +This method works for providers that accept the `x-access-token` Basic auth pattern, such as GitHub. Example usage: ```console $ export GIT_AUTH_TOKEN=$(gh auth token) From 1647d8f95de35b0e07538c1616772ef2281d60a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?JC=20Gr=C3=BCnhage?= Date: Fri, 24 Apr 2026 10:33:24 +0200 Subject: [PATCH 7/8] Update content/manuals/build/building/secrets.md Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/build/building/secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/building/secrets.md b/content/manuals/build/building/secrets.md index e2e571b2ae87..8c3bf29b8a92 100644 --- a/content/manuals/build/building/secrets.md +++ b/content/manuals/build/building/secrets.md @@ -232,7 +232,7 @@ $ docker build \ https://github.com/example/todo-app.git ``` -#### Using GIT_AUTH_HEADER (Any Git provider) +#### Using GIT_AUTH_HEADER (custom authorization header) When you use `GIT_AUTH_HEADER`, BuildKit uses the exact value you provide as the authorization header: From a16068d5359ed417c2514c0923a8632e1decaaa1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?JC=20Gr=C3=BCnhage?= Date: Fri, 24 Apr 2026 10:33:47 +0200 Subject: [PATCH 8/8] Update content/manuals/build/building/secrets.md Co-authored-by: David Karlsson <35727626+dvdksn@users.noreply.github.com> --- content/manuals/build/building/secrets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/build/building/secrets.md b/content/manuals/build/building/secrets.md index 8c3bf29b8a92..943ac69a44a6 100644 --- a/content/manuals/build/building/secrets.md +++ b/content/manuals/build/building/secrets.md @@ -234,7 +234,7 @@ $ docker build \ #### Using GIT_AUTH_HEADER (custom authorization header) -When you use `GIT_AUTH_HEADER`, BuildKit uses the exact value you provide as the authorization header: +When you use `GIT_AUTH_HEADER`, BuildKit uses the exact value you provide as the `Authorization` header: ```http Authorization: