GitHub Actions artifact 少了 .env？upload-artifact 的隱藏檔案安全設定

為什麼 hidden files 不見了？#

從 actions/upload-artifact 的目前文件來看，hidden files 是檔名以 . 開頭的檔案，或位於以 . 開頭資料夾內的檔案；Windows 只有 hidden attribute、但沒有點號前綴的檔案，不會因此被當成 hidden file。action 預設忽略它們，是為了避免意外上傳敏感資訊。

所以先看三件事：

1. workflow 實際使用的 actions/upload-artifact major 和文件是否一致。
2. path 是否真的涵蓋檔案所在目錄，而不是只指向非隱藏子資料夾。
3. 檔案是否因前一步建置、清理或 .gitignore 之外的工具規則而根本沒有產生。

不要直接把整個 workspace 的 hidden files 都打開。.env、.npmrc、雲端憑證、.git 和 .github 都可能包含不應進 artifact 的內容。

需要隱藏檔案時，先做 allowlist#

官方 README 的示範同時開啟 include-hidden-files，並以 path pattern 排除 .production.env。可依自己的產物結構改成更窄的設定：

1
- name: Upload build output
2
  uses: actions/upload-artifact@v7
3
  with:
4
    name: build-output
5
    include-hidden-files: true
6
    if-no-files-found: error
7
    path: |
8
      dist/
9
      !dist/.env
10
      !dist/.env.*
11
      !dist/.npmrc
12
      !dist/.git/
13
      !dist/.github/

這個例子假設 hidden output 確實在 dist/，而不是整個 repository。否定 pattern 要依 action 使用的 glob 行為和實際路徑測試；若產物目錄會被第三方套件寫入，先在 runner 上列出檔名和大小，再決定是否允許上傳。

1
- name: Inspect artifact files
2
  run: |
3
    find dist -type f -print
4
    if find dist -type f \( -name '.env' -o -name '.npmrc' \) -print -quit | grep -q .; then
5
      echo 'Sensitive file found in artifact directory'
6
      exit 1
7
    fi

檢查步驟不要把檔案內容印到 log；只印路徑、大小或 hash。if-no-files-found: error 也很重要，因為它能讓「原本期待的 hidden output 沒有產生」變成失敗，而不是綠燈後才在下載 artifact 時發現空目錄。

不一定要直接上傳 hidden files#

如果 artifact 需要保留一組隱藏檔案與目錄，先建立明確的 tar archive 往往比較容易做內容檢查：

1
- name: Package selected output
2
  run: |
3
    tar -cvf build-output.tar -C dist .output .config public
4

5
- name: Upload archive
6
  uses: actions/upload-artifact@v7
7
  with:
8
    name: build-output
9
    if-no-files-found: error
10
    path: build-output.tar
11
    archive: false

上傳前仍要檢查 tar 內容：

1
tar -tf build-output.tar

官方文件指出，壓縮 artifact 上傳不會保留原始檔案權限；若要保留 executable bit 和大小寫，先打包 tar，再以單一檔案、archive: false 上傳。這個方法不是安全掃描器，仍要把 .env* 和 credential 檔排除在 tar 建立清單之外。

版本與驗證要一起固定#

actions/upload-artifact 的 hidden file 行為在 action 版本演進中曾變更；官方 migration 文件指出，較新的版本預設不再包含 hidden files。不要只在 workflow comment 寫「這裡要上傳 dotfiles」，而要把 action major、allowlist、排除規則與驗證命令放在同一次變更中。

若 workflow 在 GitHub Enterprise Server 上執行，也要先確認 action v4+ 的平台支援限制；GitHub action 官方 README 有列出相容性說明。版本、平台與 artifact 下載端都固定後，再把它接到部署或測試 job，避免不同 runner 對內容有不同期待。

這類產物與 cache 的信任模型不同：cache 只應保存可重建資料，artifact 則應保存明確的 workflow output。若 artifact 會被後續 job 取回執行，接著檢查 GitHub Actions cache 的 restore-keys 安全邊界，不要把兩者都當成可信的檔案倉庫。

常見問題#