用 gitleaks 在提交前攔下機密：在 push 之前堵住 API 金鑰洩漏

適用對象：在個人開發或小團隊中使用 Git，擔心「會不會不小心把 API 金鑰提交上去」的人。這裡不講攻擊者的手法，只講阻止機密從自己的儲存庫外洩的機制。

為什麼要在「提交前」攔下

機密之所以危險，是因為 Git 會永久保留歷史。從最新的檔案刪除，它仍留在過去的提交中。而且一旦 push，那段歷史就會被複製到其他電腦、伺服器和 CI 記錄。

所以機密防護的重點其實是外洩前的預防，而不是外洩後的補救。這和「不要把機密留在公開目錄」的盤點（→ 公開目錄的盤點）是同樣的想法，只是套用到程式碼上。

在哪些階段檢出機密

在機密從程式碼流向外界的路徑上，可以設置兩道檢查：本機提交的當下，以及分享出去之前（CI）。

如何導入 gitleaks

該用哪個指令（v8.19.0 以後）

gitleaks 在 v8.19.0 重新整理了指令。舊的 detect 和 protect 仍可執行，但已棄用，也不再出現在說明中。新的設定請使用以下指令：

gitleaks 找到至少一筆外洩時以結束碼 1 結束，沒有找到時為 0，所以 CI 和 cron 工作可以依結束碼判定失敗。加上 --redact，機密本身就不會出現在輸出或記錄中。

設定範例：pre-commit 掛鉤與 GitHub Actions

使用 pre-commit 框架時，把這個檔案放在儲存庫根目錄。加入時把 rev 設為最新版本（截至 2026 年 10 月為 v8.30.1）。

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1
    hooks:
      - id: gitleaks

除了 gitleaks（以 Go 建置）之外，id 也可以是 gitleaks-docker（在 Docker 中執行）或 gitleaks-system（使用電腦上已安裝的 gitleaks）。接著每個人在自己的電腦上執行：

pip install pre-commit        # install pre-commit itself
pre-commit install            # register the hook in this repo (once per clone)
pre-commit run --all-files    # check every file once, right after registering
pre-commit autoupdate         # run now and then to move rev to a newer release

GitHub 上的 CI 有官方的 GitHub Action。它需要完整的歷史，所以用 fetch-depth: 0 進行 checkout。

# .github/workflows/gitleaks.yml
name: gitleaks
on:
  pull_request:
  push:
  schedule:
    - cron: "0 4 * * *"
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v3
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

組織帳號擁有的儲存庫，這個 Action 需要授權金鑰（GITLEAKS_LICENSE）。官方 README 表示，這個金鑰可以從 gitleaks.io 免費取得，個人帳號則不需要。在自架 Git 伺服器或 GitHub 以外的 CI 上，在工作中執行 gitleaks git --redact 也能達到相同效果。

在哪裡檢查：四個位置的比較

任何單一檢查都有漏洞。把每一個能攔下什麼、會在哪裡漏掉排列出來，就能看出為什麼要組合使用。

GitHub 針對使用者的 push protection 在推送到公開儲存庫時預設開啟。它是免費的安全網，但不會攔下本機提交，不支援格式的金鑰或手動組合的連線字串也可能通過（詳見 為什麼在 GitHub 上曝光的憑證仍然有效，英文）。gitleaks 涵蓋的是它之前的步驟，以及 GitHub 以外的所有地方。

如何檢查自己的環境

設定過一次不代表它正在運作。在你自己的儲存庫中，依序確認以下事項。

處理誤報

測試用的假金鑰和文件中的範例常常被標記。排除方法有三種；請使用可行範圍內最窄的那一種。

• 以行為單位：在那一行加上 gitleaks:allow 註解
• 以檢出結果為單位：把輸出中顯示的指紋加入儲存庫根目錄的 .gitleaksignore（README 將此標為實驗性功能）
• 以檔案或模式為單位：加入 .gitleaks.toml 的 allowlist

如果自己撰寫 .gitleaks.toml，在 [extend] 底下加上 useDefault = true 以保留預設規則。只有自訂規則的設定檔，會默默漏掉預設規則本來能抓到的金鑰。

如果舊儲存庫已有大量檢出結果，把過去的報告傳給 --baseline-path，就只會回報新的檢出結果。不過，請先撤銷報告中的金鑰。把金鑰放進 baseline，並不會讓它變安全。

常見錯誤與修正

• 以為有設定檔就夠了：在有人執行 pre-commit install 之前，掛鉤不會做任何事。請每個人都執行，並在 CI 中執行相同的檢查作為第二層。
• 習慣了 --no-verify：把 CI 檢查設為合併的必要條件，這樣即使略過掛鉤也能被抓到。
• 把機密印到 CI 記錄中：加上 --redact。CI 記錄也有很多人能看到。
• 在 CI 中掃描淺層 clone：只會檢查最新的提交，歷史中的機密會被漏掉。設定 fetch-depth: 0。
• 從歷史刪除後就停下：GitHub 自己的指南把撤銷或輪換機密列為第一步。fork、clone 和快取中的副本無法刪除。
• 把真正的金鑰當作「誤報」加入 allowlist：在註解中寫下理由，並在審查時確認。

實際案例：存取金鑰被公開

2022 年 10 月 7 日，豐田汽車（Toyota Motor Corporation）宣布，其連網汽車服務 T-Connect 使用者網站的部分原始碼曾在 GitHub 上公開。根據該公司的公告：

• 2017 年 12 月，負責開發該網站的委外廠商誤將部分原始碼上傳到設為公開的 GitHub 帳號
• 程式碼中包含存放客戶資訊的資料伺服器存取金鑰
• 程式碼在 2022 年 9 月 15 日改為非公開，存取金鑰在 9 月 17 日更換
• 受影響的是 296,019 筆電子郵件地址和客戶管理編號。存取記錄中沒有發現第三方使用，但該公司表示無法完全排除

從上傳到移除大約經過了五年。而且它發生在公司自己的儲存庫之外，也就是委外廠商的帳號中。對自己儲存庫的掃描，無法觸及你的程式碼最終流向的每個地方，所以也要限制每把金鑰能做的事，並定期輪換金鑰。即使在這個案例中，金鑰也是在程式碼下架兩天後才更換：找到之後，就要更換金鑰。

私有儲存庫也不是存放機密的安全地方。在 CAMPFIRE 2026 年的案例中，據該公司表示，遭濫用的 GitHub 憑證是起點，在 GitHub 上可以看到的資訊被用來取得雲端憑證（→ CAMPFIRE 外洩事件，英文）。私有儲存庫也不要放機密，並且用 gitleaks 定期掃描。

本站是怎麼做的

本站的基本規則是機密完全不放進 Git：連線字串和 API 金鑰只放在伺服器上受保護的設定中（權限受限的 env 檔），既不以明文放在儲存庫裡，也不放在交接筆記中（→ 不把機密放進 git／自架 Git vs GitHub）。在此之上，再以人一定會出錯為前提，疊加檢測工具。設計保證「不放進去」，gitleaks 這類掃描則抓住「還是放進去了」的情況，這兩層就是本站防止機密外洩的做法。處理機密的原則本身，與 .env 檔與機密和安全保存密碼相同。

接下來閱讀

• GitHub 設定：如何設定 GitHub 雙重驗證
• 基礎：.env 檔和 API 金鑰：會出什麼問題、如何保護
• 從 GitHub 憑證到外洩：CAMPFIRE 外洩事件（2026）（英文）
• 外洩之後：在 GitHub 上曝光的 543,699 筆憑證仍然有效：為什麼必須撤銷，而不只是刪除（英文）
• 攻擊在無人操作下進行時：Hugging Face 入侵事件，以及防守方必須放棄的假設
• 盤點：有沒有把機密留在公開目錄裡
• 自架：不把機密放進 git／自架 Git vs GitHub
• 術語：什麼是「.env」：環境變數檔外洩會發生什麼
• 工具：機密外洩檢查工具（貼上檢查）

出處

• gitleaks（官方儲存庫）README：指令（git、dir、stdin）、v8.19.0 中 detect/protect 的棄用、結束碼、--redact、gitleaks:allow、.gitleaksignore、--baseline-path、設定的擴充 — github.com/gitleaks/gitleaks / 官方掛鉤定義 — .pre-commit-hooks.yaml / Releases
• gitleaks-action（官方 GitHub Action）README：工作流程範例與授權金鑰 — github.com/gitleaks/gitleaks-action
• pre-commit 文件（install、run --all-files、autoupdate、SKIP）— pre-commit.com
• Git 文件「githooks」（pre-commit 掛鉤與 --no-verify）— git-scm.com
• GitHub Docs「About push protection」— docs.github.com / 「Removing sensitive data from a repository」— docs.github.com
• 豐田汽車，關於客戶電子郵件地址可能外洩的公告（2022 年 10 月 7 日，日文）— global.toyota