Merge pull request #24114 from docker/agent/issue-23189

docs: address issue #23189

content/guides/angular/configure-github-actions.md

@@ -158,7 +158,7 @@ jobs:
     steps:
       # 1. Checkout source code
       - name: Checkout source code
-        uses: actions/checkout@v4
+        uses: actions/checkout@{{% param "checkout_action_version" %}}
         with:
           fetch-depth: 0
 
@@ -168,7 +168,7 @@ jobs:
 
       # 3. Cache Docker layers
       - name: Cache Docker layers
-        uses: actions/cache@v4
+        uses: actions/cache@{{% param "cache_action_version" %}}
         with:
           path: /tmp/.buildx-cache
           key: ${{ runner.os }}-buildx-${{ github.sha }}
@@ -177,7 +177,7 @@ jobs:
 
       # 4. Cache npm dependencies
       - name: Cache npm dependencies
-        uses: actions/cache@v4
+        uses: actions/cache@{{% param "cache_action_version" %}}
         with:
           path: ~/.npm
           key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

content/guides/gha.md

@@ -103,7 +103,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@{{% param "checkout_action_version" %}}
       - name: Extract Docker image metadata
         id: meta
         uses: docker/metadata-action@{{% param "metadata_action_version" %}}
@@ -216,7 +216,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@{{% param "checkout_action_version" %}}
 
       - name: Extract Docker image metadata
         id: meta

content/guides/github-sonarqube-sandbox/customize.md

@@ -62,10 +62,10 @@ jobs:
   quality:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@{{% param "checkout_action_version" %}}
+      - uses: actions/setup-node@v5
         with:
-          node-version: "18"
+          node-version: "24"
       - run: npm install
       - run: npx tsx 06-quality-gated-pr.ts
         env:
@@ -91,10 +91,10 @@ jobs:
   quality:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@{{% param "checkout_action_version" %}}
+      - uses: actions/setup-python@v6
         with:
-          python-version: "3.8"
+          python-version: "3.14"
       - run: pip install e2b python-dotenv
       - run: python 06_quality_gated_pr.py
         env:

content/guides/nodejs/configure-github-actions.md

@@ -175,13 +175,13 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@{{% param "checkout_action_version" %}}
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
 
       - name: Cache npm dependencies
-        uses: actions/cache@v4
+        uses: actions/cache@{{% param "cache_action_version" %}}
         with:
           path: ~/.npm
           key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
@@ -220,13 +220,13 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@{{% param "checkout_action_version" %}}
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
 
       - name: Cache Docker layers
-        uses: actions/cache@v4
+        uses: actions/cache@{{% param "cache_action_version" %}}
         with:
           path: /tmp/.buildx-cache
           key: ${{ runner.os }}-buildx-${{ github.sha }}

content/guides/python/configure-github-actions.md

@@ -63,12 +63,12 @@ jobs:
   lint-test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@{{% param "checkout_action_version" %}}
       
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
-          python-version: '3.12'
+          python-version: '3.14'
 
       - name: Install dependencies
         run: |

content/guides/reactjs/configure-github-actions.md

@@ -158,7 +158,7 @@ jobs:
     steps:
       # 1. Checkout source code
       - name: Checkout source code
-        uses: actions/checkout@v4
+        uses: actions/checkout@{{% param "checkout_action_version" %}}
         with:
           fetch-depth: 0 # Fetches full history for better caching/context
 
@@ -168,7 +168,7 @@ jobs:
 
       # 3. Cache Docker layers
       - name: Cache Docker layers
-        uses: actions/cache@v4
+        uses: actions/cache@{{% param "cache_action_version" %}}
         with:
           path: /tmp/.buildx-cache
           key: ${{ runner.os }}-buildx-${{ github.sha }}
@@ -176,7 +176,7 @@ jobs:
 
       # 4. Cache npm dependencies
       - name: Cache npm dependencies
-        uses: actions/cache@v4
+        uses: actions/cache@{{% param "cache_action_version" %}}
         with:
           path: ~/.npm
           key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

content/guides/vuejs/configure-github-actions.md

@@ -158,7 +158,7 @@ jobs:
     steps:
       # 1. Checkout the codebase
       - name: Checkout Code
-        uses: actions/checkout@v4
+        uses: actions/checkout@{{% param "checkout_action_version" %}}
         with:
           fetch-depth: 0
 
@@ -168,7 +168,7 @@ jobs:
 
       # 3. Cache Docker layers
       - name: Cache Docker Layers
-        uses: actions/cache@v4
+        uses: actions/cache@{{% param "cache_action_version" %}}
         with:
           path: /tmp/.buildx-cache
           key: ${{ runner.os }}-buildx-${{ github.sha }}
@@ -177,7 +177,7 @@ jobs:
 
       # 4. Cache npm dependencies
       - name: Cache npm Dependencies
-        uses: actions/cache@v4
+        uses: actions/cache@{{% param "cache_action_version" %}}
         with:
           path: ~/.npm
           key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}

content/manuals/build/ci/github-actions/cache.md

@@ -246,7 +246,7 @@ jobs:
             type=semver,pattern={{major}}.{{minor}}
 
       - name: Go Build Cache for Docker
-        uses: actions/cache@v4
+        uses: actions/cache@{{% param "cache_action_version" %}}
         with:
           path: go-build-cache
           key: ${{ runner.os }}-go-build-cache-${{ hashFiles('**/go.sum') }}
@@ -303,7 +303,7 @@ jobs:
         uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
 
       - name: Cache Docker layers
-        uses: actions/cache@v4
+        uses: actions/cache@{{% param "cache_action_version" %}}
         with:
           path: ${{ runner.temp }}/.buildx-cache
           key: ${{ runner.os }}-buildx-${{ github.sha }}

content/manuals/build/ci/github-actions/configure-builder.md

@@ -266,7 +266,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@{{% param "checkout_action_version" %}}
       
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}

content/manuals/build/ci/github-actions/secrets.md

@@ -57,14 +57,119 @@ jobs:
             "github_token=${{ secrets.GITHUB_TOKEN }}"
 ```
 
-> [!NOTE]
->
-> You can also expose a secret file to the build with the `secret-files` input:
->
-> ```yaml
-> secret-files: |
->   "MY_SECRET=./secret.txt"
-> ```
+### Using secret files
+
+The `secret-files` input lets you mount existing files as secrets in your build.
+This is useful when you need to use credential files that are generated during your workflow,
+or when you need to mount configuration files like `.npmrc` or `.pypirc` that are already in the expected format.
+
+The key difference between `secrets` and `secret-files`:
+
+- `secrets`: Pass secret values as strings (from environment variables or GitHub secrets)
+- `secret-files`: Mount existing files from the runner's filesystem
+
+#### Example: Using .npmrc for private npm packages
+
+If your build needs to install packages from a private npm registry,
+you can create an `.npmrc` file and mount it as a secret:
+
+```yaml
+name: ci
+
+on:
+  push:
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@{{% param "checkout_action_version" %}}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
+
+      - name: Create .npmrc file
+        run: |
+          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc
+
+      - name: Build
+        uses: docker/build-push-action@{{% param "build_push_action_version" %}}
+        with:
+          context: .
+          secret-files: |
+            npmrc=./.npmrc
+          tags: user/app:latest
+```
+
+In your Dockerfile, mount the secret file to the expected location:
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+
+RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
+    npm ci
+
+COPY . .
+
+RUN npm run build
+```
+
+#### Example: Using dynamically generated credentials
+
+You can generate credential files from multiple secrets and mount them:
+
+```yaml
+name: ci
+
+on:
+  push:
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@{{% param "checkout_action_version" %}}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
+
+      - name: Create credentials file
+        run: |
+          cat <<EOF > aws-credentials
+          [default]
+          aws_access_key_id = ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws_secret_access_key = ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          EOF
+
+      - name: Build
+        uses: docker/build-push-action@{{% param "build_push_action_version" %}}
+        with:
+          context: .
+          secret-files: |
+            aws=./aws-credentials
+          tags: user/app:latest
+```
+
+In your Dockerfile:
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM alpine
+
+RUN apk add --no-cache aws-cli
+
+RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
+    aws s3 cp s3://my-private-bucket/data.tar.gz /tmp/
+```
+
+### Multi-line secrets
 
 If you're using [GitHub secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
 and need to handle multi-line value, you will need to place the key-value pair

content/manuals/build/policies/usage.md

@@ -306,7 +306,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@{{% param "checkout_action_version" %}}
       - uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
       - name: Test build with policy
         run: docker buildx build --policy strict=true .

content/manuals/dhi/how-to/scan.md

@@ -175,7 +175,7 @@ jobs:
       pull-requests: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@{{% param "checkout_action_version" %}}
 
       - name: Set up Docker with containerd image store
         uses: docker/setup-docker-action@{{% param "setup_docker_action_version" %}}

hugo.yaml

@@ -159,6 +159,9 @@ params:
   setup_docker_action_version: "v5"
   setup_qemu_action_version: "v4"
   github_builder_version: "v1"
+  # Generic actions
+  checkout_action_version: "v6"
+  cache_action_version: "v5"
 
   # Example runtime/library/os versions
   example_go_version: "1.25"