Docker Build secrets 怎麼用？用 --secret 取代 ARG 與 ENV

為什麼 ARG 與 ENV 不適合放建置憑證#

下面這種寫法看起來方便，卻把 token 帶進不該出現的邊界：

1
ARG NPM_TOKEN
2
RUN npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN && npm ci

Docker 官方 Dockerfile reference 將 ARG 定義為建置時變數，並提醒不要把秘密當成 build arg；ENV 則會成為 image configuration 的一部分，之後的 layer 或 container 都可能繼承。即使某次 build 沒有直接看到明文，也不要把「沒有在終端機印出」當成「已安全保存」。

這也和 Docker COPY 找不到檔案的 build context 邊界不同：secret 不應為了讓 COPY 找得到而被放進 context。

用檔案 secret 安裝私有 npm 套件#

如果 npm 已經使用 .npmrc 設定 registry credential，可以把它當成 file secret：

1
# syntax=docker/dockerfile:1
2
FROM node:22-alpine
3

4
WORKDIR /app
5
COPY package*.json ./
6

7
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true \
8
    npm ci
9

10
COPY . .
11
CMD ["npm", "start"]

建置時指定同一個 secret ID：

1
docker build \
2
  --secret id=npmrc,src="$HOME/.npmrc" \
3
  --tag example-app:build-secrets .

id 連接 CLI 的來源與 Dockerfile 的 mount；target 讓 npm 使用它原本會讀取的路徑；required=true 則把「漏傳 credential」提早變成明確的 mount 錯誤。不要把 .npmrc 加到 COPY，也不要把 secret 內容插值到另一個會留在 layer 的檔案。

Docker 官方文件也支援用 environment variable 作為來源或掛載結果。需要讓命令讀取環境變數時，可用：

1
docker build \
2
  --secret id=API_TOKEN,env=API_TOKEN \
3
  --tag example-app:build-secrets .

1
RUN --mount=type=secret,id=API_TOKEN,env=API_TOKEN \
2
    ./scripts/private-build.sh

如果使用 src=API_TOKEN 表示環境變數名稱，請明確寫 type=env；否則 Buildx 可能把它當成相對於目前目錄的檔案來源。建置腳本也要避免 set -x、debug log 或錯誤訊息把環境值印出來。

私有 Git repository 改用 SSH mount#

要在 build 中執行 git clone [email protected]:... 或安裝需要 SSH 的依賴時，通常應傳 SSH agent，而不是把私鑰當檔案 secret 複製進去：

1
# syntax=docker/dockerfile:1
2
FROM alpine
3

4
RUN apk add --no-cache git openssh-client
5
RUN --mount=type=ssh \
6
    git clone [email protected]:example/private-repo.git /src

1
docker buildx build --ssh default --tag example-private-build .

SSH mount 和 secret mount 都是暫時掛載，但用途不同：前者連到 SSH agent socket，後者通常把 token 或設定檔掛成檔案／環境變數。先看工具需要哪種 credential，再選 mount 類型。

注意 secret 不會自動讓 cache 失效#

Docker 官方 cache 文件明確指出，secret 的內容不參與 build cache checksum。也就是說，token 變更不會因為內容不同而自動重跑同一個 RUN。如果命令的輸出真的會隨 secret 變更，應另外傳入不含秘密的 cache bust 值：

1
ARG CACHEBUST=0
2
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc,required=true \
3
    npm ci

1
docker build \
2
  --secret id=npmrc,src="$HOME/.npmrc" \
3
  --build-arg CACHEBUST=2 \
4
  --tag example-app:build-secrets .

CACHEBUST 只應是版本或計數器，不要把 token 本身放進 ARG 來觸發 cache。若秘密只影響認證、不影響輸出，則不要為了輪替 token 而破壞整個依賴安裝 cache。

在 GitHub Actions 中傳給 Buildx#

CI 不應把 token 寫進 workflow YAML。Docker 的 GitHub Actions 文件提供 secret-envs 與 secret-files，把 GitHub Secret 映射到 BuildKit secret：

1
name: Build image
2

3
on:
4
  push:
5

6
jobs:
7
  docker:
8
    runs-on: ubuntu-latest
9
    steps:
10
      - uses: actions/checkout@v6
11
      - uses: docker/setup-buildx-action@v4
12
      - uses: docker/build-push-action@v7
13
        env:
14
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
15
        with:
16
          context: .
17
          push: false
18
          secret-envs: |
19
            npm_token=NPM_TOKEN
20
          tags: example/app:test

Dockerfile 端對應：

1
RUN --mount=type=secret,id=npm_token,env=NPM_TOKEN,required=true \
2
    npm run build

這個 workflow 仍要依 repository 的 trigger、fork PR 權限與 action pinning 做安全審查；secret-envs 只解決 credential 進入 BuildKit 的路徑，不會自動允許不可信的 pull request 讀取 production secret。

發布前驗證秘密沒有進 image#

至少做一次不含真實 credential 的測試，並檢查建置輸出：

1. RUN --mount=type=secret 少了 required=true 時，確認你知道工具會如何失敗。
2. 故意讓命令只讀取 mount，不把值寫到工作目錄或輸出 artifact。
3. 用 docker history --no-trunc <image> 檢查 command 文字沒有出現 token。
4. 用 docker image inspect <image> 檢查 Config.Env 沒有不應公開的 credential。
5. 檢查 CI log 沒有 set -x、debug dump 或錯誤堆疊洩漏秘密。

這些檢查不能取代 credential rotation；如果秘密曾經放進 Git、image 或公開 log，先撤銷並輪替，再修正 Dockerfile。安全的 mount 只保護正確使用它的路徑。

把規則記成一句話：建置需要秘密，就讓它只在一個 RUN 指令裡短暫出現；不要讓秘密成為 Dockerfile 的參數、環境設定或複製檔案。

常見問題#