docs: address issue #23189

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@v4
+
+      - 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@v4
+
+      - 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