From 4f1906aad9cd12f123b40b3f4cb9e06246bdd45c Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Wed, 3 Dec 2025 10:50:39 +0100
Subject: [PATCH] build: deprecate install input for setup-buildx-action

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/manuals/build-cloud/ci.md    | 26 +++++++++++++++++++++++++-
 content/manuals/build-cloud/usage.md | 10 +++++-----
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/content/manuals/build-cloud/ci.md b/content/manuals/build-cloud/ci.md
index 49477182d55a..2479b06ea684 100644
--- a/content/manuals/build-cloud/ci.md
+++ b/content/manuals/build-cloud/ci.md
@@ -100,7 +100,6 @@ jobs:
         with:
           driver: cloud
           endpoint: "${{ vars.DOCKER_ACCOUNT }}/${{ vars.CLOUD_BUILDER_NAME }}" # for example, "acme/default"
-          install: true
       
       - name: Build and push
         uses: docker/build-push-action@v6
@@ -111,6 +110,31 @@ jobs:
           outputs: ${{ github.event_name == 'pull_request' && 'type=cacheonly' || 'type=registry' }}
 ```
 
+The example above uses `docker/build-push-action`, which automatically uses the
+builder set up by `setup-buildx-action`. If you need to use the `docker build`
+command directly instead, you have two options:
+
+- Use `docker buildx build` instead of `docker build`
+- Set the `BUILDX_BUILDER` environment variable to use the cloud builder:
+
+  ```yaml
+  - name: Set up Docker Buildx
+    id: builder
+    uses: docker/setup-buildx-action@v3
+    with:
+      driver: cloud
+      endpoint: "${{ vars.DOCKER_ACCOUNT }}/${{ vars.CLOUD_BUILDER_NAME }}"
+
+  - name: Build
+    run: |
+      docker build .
+    env:
+      BUILDX_BUILDER: ${{ steps.builder.outputs.name }}
+  ```
+
+For more information about the `BUILDX_BUILDER` environment variable, see
+[Build variables](/manuals/build/building/variables.md#buildx_builder).
+
 ### GitLab
 
 ```yaml
diff --git a/content/manuals/build-cloud/usage.md b/content/manuals/build-cloud/usage.md
index 891bb7df9cf2..b961398b3dfb 100644
--- a/content/manuals/build-cloud/usage.md
+++ b/content/manuals/build-cloud/usage.md
@@ -45,11 +45,11 @@ Changing your default builder with `docker buildx use` only changes the default
 builder for the `docker buildx build` command. The `docker build` command still
 uses the `default` builder, unless you specify the `--builder` flag explicitly.
 
-If you use build scripts, such as `make`, we recommend that you update your
-build commands from `docker build` to `docker buildx build`, to avoid any
-confusion with regards to builder selection. Alternatively, you can run `docker
-buildx install` to make the default `docker build` command behave like `docker
-buildx build`, without discrepancies.
+If you use build scripts, such as `make`, that use the `docker build` command,
+we recommend updating your build commands to `docker buildx build`. Alternatively,
+you can set the [`BUILDX_BUILDER` environment
+variable](/manuals/build/building/variables.md#buildx_builder) to specify which
+builder `docker build` should use.
 
 ## Use with Docker Compose