docs(ci): clarify builder and credential variables for CI setup (DCL-248)

Author: nico1510

content/manuals/build-cloud/ci.md

@@ -36,42 +36,42 @@ See [Loading build results](./usage/#loading-build-results) for details.
 
 To enable your CI/CD system to build and push images using Docker Build Cloud, provide both an access token and a username. The type of token and the username you use depend on your account type and permissions.
 
-- If you are an organization administrator or have permission to create [organization access tokens (OAT)](../security/for-admins/access-tokens.md), use an OAT and set `DOCKER_USER` to your Docker Hub organization name.
-- If you do not have permission to create OATs or are using a personal account, use a [personal access token (PAT)](/security/for-developers/access-tokens/) and set `DOCKER_USER` to your Docker Hub username.
+- If you are an organization administrator or have permission to create [organization access tokens (OAT)](../security/for-admins/access-tokens.md), use an OAT and set `DOCKER_ACCOUNT` to your Docker Hub organization name.
+- If you do not have permission to create OATs or are using a personal account, use a [personal access token (PAT)](/security/for-developers/access-tokens/) and set `DOCKER_ACCOUNT` to your Docker Hub username.
 
 ### Creating access tokens
 
 #### For organization accounts
 
 If you are an organization administrator:
 
-1. Create an [organization access token (OAT)](../security/for-admins/access-tokens.md):
-   - The token must have these permissions:
-     - **cloud-connect** scope
-     - **Read public repositories** permission
-     - **Repository access** with **Image push** permission for the target repository:
-       - Expand the **Repository** drop-down.
-       - Select **Add repository** and choose your target repository.
-       - Set the **Image push** permission for the repository.
+- Create an [organization access token (OAT)](../security/for-admins/access-tokens.md). The token must have these permissions:
+    1. **cloud-connect** scope
+    2. **Read public repositories** permission
+    3. **Repository access** with **Image push** permission for the target repository:
+        - Expand the **Repository** drop-down.
+        - Select **Add repository** and choose your target repository.
+        - Set the **Image push** permission for the repository.
 
 If you are not an organization administrator:
 
 - Ask your organization administrator for an access token with the permissions listed above, or use a personal access token.
 
 #### For personal accounts
 
-1. Create a [personal access token (PAT)](/security/for-developers/access-tokens/):
-   - Create a new token with **Read & write** access.
-     - Note: Building with Docker Build Cloud only requires read access, but you need write access to push images to a Docker Hub repository.
+- Create a [personal access token (PAT)](/security/for-developers/access-tokens/) with the following permissions:
+   1. **Read & write** access.
+        - Note: Building with Docker Build Cloud only requires read access, but you need write access to push images to a Docker Hub repository.
 
 
 ## CI platform examples
 
 > [!NOTE]
 >
-> In your CI/CD configuration, set the following variables:
-> - `DOCKER_PAT` — your access token (PAT or OAT)
-> - `DOCKER_USER` — your Docker Hub username (for PAT) or organization name (for OAT)
+> In your CI/CD configuration, set the following variables/secrets:
+> - `DOCKER_ACCESS_TOKEN` — your access token (PAT or OAT). Use a secret to store the token.
+> - `DOCKER_ACCOUNT` — your Docker Hub organization name (for OAT) or username (for PAT)
+> - `CLOUD_BUILDER_NAME` — the name of the cloud builder you created in the [Docker Build Cloud Dashboard](https://app.docker.com/build/)
 >
 > This ensures your builds authenticate correctly with Docker Build Cloud.
 
@@ -92,20 +92,20 @@ jobs:
       - name: Login to Docker Hub
         uses: docker/login-action@v3
         with:
-          username: ${{ vars.DOCKER_USER }}
-          password: ${{ secrets.DOCKER_PAT }}
+          username: ${{ vars.DOCKER_ACCOUNT }}
+          password: ${{ secrets.DOCKER_ACCESS_TOKEN }}
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
         with:
           driver: cloud
-          endpoint: "<ORG>/default"
+          endpoint: "${{ vars.DOCKER_ACCOUNT }}/${{ vars.CLOUD_BUILDER_NAME }}" # for example, "acme/default"
           install: true
 
       - name: Build and push
         uses: docker/build-push-action@v6
         with:
-          tags: "<IMAGE>"
+          tags: "<IMAGE>" # for example, "acme/my-image:latest"
           # For pull requests, export results to the build cache.
           # Otherwise, push to a registry.
           outputs: ${{ github.event_name == 'pull_request' && 'type=cacheonly' || 'type=registry' }}
@@ -120,19 +120,20 @@ default:
     - docker:24-dind
   before_script:
     - docker info
-    - echo "$DOCKER_PAT" | docker login --username "$DOCKER_USER" --password-stdin
+    - echo "$DOCKER_ACCESS_TOKEN" | docker login --username "$DOCKER_ACCOUNT" --password-stdin
     - |
       apk add curl jq
       ARCH=${CI_RUNNER_EXECUTABLE_ARCH#*/}
       BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
       mkdir -vp ~/.docker/cli-plugins/
       curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
       chmod a+x ~/.docker/cli-plugins/docker-buildx
-    - docker buildx create --use --driver cloud ${DOCKER_ORG}/default
+    - docker buildx create --use --driver cloud ${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}
 
 variables:
   IMAGE_NAME: <IMAGE>
-  DOCKER_ORG: <ORG>
+  DOCKER_ACCOUNT: <DOCKER_ACCOUNT> # your Docker Hub organization name (or username when using a personal account)
+  CLOUD_BUILDER_NAME: <CLOUD_BUILDER_NAME> # the name of the cloud builder you created in the [Docker Build Cloud Dashboard](https://app.docker.com/build/)
 
 # Build multi-platform image and push to a registry
 build_push:
@@ -176,8 +177,8 @@ jobs:
           curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
           chmod a+x ~/.docker/cli-plugins/docker-buildx
 
-      - run: echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
-      - run: docker buildx create --use --driver cloud "<ORG>/default"
+      - run: echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ --password-stdin
+      - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
       - run: |
           docker buildx build \
@@ -199,8 +200,8 @@ jobs:
           curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
           chmod a+x ~/.docker/cli-plugins/docker-buildx
 
-      - run: echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
-      - run: docker buildx create --use --driver cloud "<ORG>/default"
+      - run: echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ --password-stdin
+      - run: docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
       - run: |
           docker buildx build \
@@ -231,24 +232,25 @@ Add the following `environment` hook agent's hook directory:
 set -euo pipefail
 
 if [[ "$BUILDKITE_PIPELINE_NAME" == "build-push-docker" ]]; then
- export DOCKER_PAT="<DOCKER_PERSONAL_ACCESS_TOKEN>"
+ export DOCKER_ACCESS_TOKEN="<DOCKER_ACCESS_TOKEN>"
 fi
 ```
 
 Create a `pipeline.yml` that uses the `docker-login` plugin:
 
 ```yaml
 env:
-  DOCKER_ORG: <ORG>
+  DOCKER_ACCOUNT: <DOCKER_ACCOUNT> # your Docker Hub organization name (or username when using a personal account)
+  CLOUD_BUILDER_NAME: <CLOUD_BUILDER_NAME> # the name of the cloud builder you created in the [Docker Build Cloud Dashboard](https://app.docker.com/build/)
   IMAGE_NAME: <IMAGE>
 
 steps:
   - command: ./build.sh
     key: build-push
     plugins:
       - docker-login#v2.1.0:
-          username: <DOCKER_USER>
-          password-env: DOCKER_PAT # the variable name in the environment hook
+          username: DOCKER_ACCOUNT
+          password-env: DOCKER_ACCESS_TOKEN # the variable name in the environment hook
 ```
 
 Create the `build.sh` script:
@@ -277,7 +279,7 @@ curl --silent -L --output $DOCKER_DIR/cli-plugins/docker-buildx $BUILDX_URL
 chmod a+x ~/.docker/cli-plugins/docker-buildx
 
 # Connect to your builder and set it as the default builder
-docker buildx create --use --driver cloud "$DOCKER_ORG/default"
+docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
 # Cache-only image build
 docker buildx build \
@@ -302,9 +304,9 @@ pipeline {
 
   environment {
     ARCH = 'amd64'
-    DOCKER_PAT = credentials('docker-personal-access-token')
-    DOCKER_USER = credentials('docker-username')
-    DOCKER_ORG = '<ORG>'
+    DOCKER_ACCESS_TOKEN = credentials('docker-access-token')
+    DOCKER_ACCOUNT = credentials('docker-account')
+    CLOUD_BUILDER_NAME = '<CLOUD_BUILDER_NAME>'
     IMAGE_NAME = '<IMAGE>'
   }
 
@@ -317,8 +319,8 @@ pipeline {
         sh 'mkdir -vp ~/.docker/cli-plugins/'
         sh 'curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL'
         sh 'chmod a+x ~/.docker/cli-plugins/docker-buildx'
-        sh 'echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin'
-        sh 'docker buildx create --use --driver cloud "$DOCKER_ORG/default"'
+        sh 'echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin'
+        sh 'docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"'
         // Cache-only build
         sh 'docker buildx build --platform linux/amd64,linux/arm64 --tag "$IMAGE_NAME" --output type=cacheonly .'
         // Build and push a multi-platform image
@@ -340,18 +342,18 @@ services:
 
 env:
   global:
-    - IMAGE_NAME=username/repo
+    - IMAGE_NAME=<IMAGE> # for example, "acme/my-image:latest"
 
 before_install: |
-  echo "$DOCKER_PAT" | docker login --username "$DOCKER_USER" --password-stdin
+  echo "$DOCKER_ACCESS_TOKEN" | docker login --username "$DOCKER_ACCOUNT" --password-stdin
 
 install: |
   set -e 
   BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$TRAVIS_CPU_ARCH\"))")
   mkdir -vp ~/.docker/cli-plugins/
   curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
   chmod a+x ~/.docker/cli-plugins/docker-buildx
-  docker buildx create --use --driver cloud "<ORG>/default"
+  docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
 script: |
   docker buildx build \
@@ -363,9 +365,8 @@ script: |
 ### BitBucket Pipelines 
 
 ```yaml
-# Prerequisites: $DOCKER_USER, $DOCKER_PAT setup as deployment variables
+# Prerequisites: $DOCKER_ACCOUNT, $CLOUD_BUILDER_NAME, $DOCKER_ACCESS_TOKEN setup as deployment variables
 # This pipeline assumes $BITBUCKET_REPO_SLUG as the image name
-# Replace <ORG> in the `docker buildx create` command with your Docker org
 
 image: atlassian/default-image:3
 
@@ -379,8 +380,8 @@ pipelines:
           - BUILDX_URL=$(curl -s https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/buildx-lab-releases.json | jq -r ".latest.assets[] | select(endswith(\"linux-$ARCH\"))")
           - curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
           - chmod a+x ~/.docker/cli-plugins/docker-buildx
-          - echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
-          - docker buildx create --use --driver cloud "<ORG>/default"
+          - echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
+          - docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
           - IMAGE_NAME=$BITBUCKET_REPO_SLUG
           - docker buildx build
             --platform linux/amd64,linux/arm64
@@ -404,11 +405,11 @@ mkdir -vp ~/.docker/cli-plugins/
 curl --silent -L --output ~/.docker/cli-plugins/docker-buildx $BUILDX_URL
 chmod a+x ~/.docker/cli-plugins/docker-buildx
 
-# Login to Docker Hub. For security reasons $DOCKER_PAT should be a Personal Access Token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
-echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
+# Login to Docker Hub with an access token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
+echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
 
 # Connect to your builder and set it as the default builder
-docker buildx create --use --driver cloud "<ORG>/default"
+docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
 # Cache-only image build
 docker buildx build \
@@ -449,11 +450,11 @@ curl --silent -L --output ~/.docker/cli-plugins/docker-compose $COMPOSE_URL
 chmod a+x ~/.docker/cli-plugins/docker-buildx
 chmod a+x ~/.docker/cli-plugins/docker-compose
 
-# Login to Docker Hub. For security reasons $DOCKER_PAT should be a Personal Access Token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
-echo "$DOCKER_PAT" | docker login --username $DOCKER_USER --password-stdin
+# Login to Docker Hub with an access token. See https://docs.docker.com/build-cloud/ci/#creating-access-tokens
+echo "$DOCKER_ACCESS_TOKEN" | docker login --username $DOCKER_ACCOUNT --password-stdin
 
 # Connect to your builder and set it as the default builder
-docker buildx create --use --driver cloud "<ORG>/default"
+docker buildx create --use --driver cloud "${DOCKER_ACCOUNT}/${CLOUD_BUILDER_NAME}"
 
 # Build the image build
 docker compose build

content/manuals/build-cloud/setup.md

@@ -16,7 +16,8 @@ environment.
 To get started with Docker Build Cloud, you need to:
 
 - Download and install Docker Desktop version 4.26.0 or later.
-- Sign up for a Docker Build Cloud subscription in the [Docker Build Cloud Dashboard](https://app.docker.com/build/).
+- Create a cloud builder on the [Docker Build Cloud Dashboard](https://app.docker.com/build/).
+  - When you create the builder, choose a name for it (for example, `default`). You will use this name as `BUILDER_NAME` in the CLI steps below.
 
 ### Use Docker Build Cloud without Docker Desktop
 
@@ -50,9 +51,18 @@ command, or using the Docker Desktop settings GUI.
    $ docker buildx create --driver cloud <ORG>/<BUILDER_NAME>
    ```
 
-   Replace `ORG` with the Docker Hub namespace of your Docker organization.
+   Replace `<ORG>` with the Docker Hub namespace of your Docker organization (or your username if you are using a personal account), and `<BUILDER_NAME>` with the name you chose when creating the builder in the dashboard.
+
+   This creates a local instance of the cloud builder named `cloud-ORG-BUILDER_NAME`.
+
+   > [!NOTE]
+   > Example:
+   >
+   > If your organization is `acme` and you named your builder `default`, use:
+   > ```console
+   > $ docker buildx create --driver cloud acme/default
+   > ```
 
-This creates a builder named `cloud-ORG-BUILDER_NAME`.
 
 {{< /tab >}}
 {{< tab name="Docker Desktop" >}}