GitHub Code Scanning default setup 怎麼共用 CodeQL 設定檔？

github-codeql-config-file 會怎麼合併設定#

GitHub 文件的描述是：自訂設定檔會和 default setup 自動產生的內建設定合併。你可以在設定檔中加入額外 queries 或 paths-ignore，而不必為了客製化就放棄 default setup。

一份可以放在中央 repository 的設定檔，例如：

1
name: "Organization CodeQL configuration"
2

3
queries:
4
  - uses: security-extended
5

6
paths-ignore:
7
  - "generated/**"
8
  - "vendor/**"

這個檔案應該只放團隊確定要共用的規則。先不要把某個 repository 特有的路徑、暫時性 false positive 或實驗 query 直接塞進組織層級，否則排錯時很難知道問題來自中央設定還是專案本身。

用 repository property 指向設定檔#

github-codeql-config-file 是 repository property，不是 codeql.yml 自動偵測的特殊檔名。GitHub 文件提供的遠端格式是：

1
remote=octo-org/security-config@main:codeql.yml

也可以先用被分析 repository 內的本地路徑，或在單一 repository 測試遠端設定。實際 rollout 前先確認三件事：

• property 已經在組織中建立，且值是 GitHub Code Scanning 接受的本地或遠端路徑。
• 設定檔所在的 branch、路徑與 repository 可被正確讀取。
• 這個 repository 已經啟用適用的 Code Scanning setup；property 本身不會替你開啟掃描。

如果中央設定檔放在另一個 private repository，GitHub 要求另外設定 Git Source private registry，讓 security features 能讀到它。不要用工作流程裡的長期 token 來繞過這個存取邊界。

先測一個 repository，再推到整個組織#

GitHub 官方建議的 rollout 順序是先測試，再設定 organization-wide default。可以照這個流程做：

1. 在中央 repository 建立並 review CodeQL 設定檔。
2. 為組織建立 github-codeql-config-file property，但先不要立即替所有 repository 設定預設值。
3. 只在一個測試 repository 設定 local 或 remote value，等待下一次 Code Scanning 執行。
4. 對照新增的 findings、被排除的路徑與原本的語言／query 結果。
5. 確認結果可接受後，再把 property 的 default value 設成中央檔案位置。

要特別留意 repository 的明確設定：已有 explicit github-codeql-config-file 值的 repository，會繼續使用自己的值，不會被 organization-wide default 覆蓋。這是 rollout 後最容易出現「為什麼某個 repository 沒跟著改」的原因。

default setup 與 advanced setup 怎麼選#

如果真正的需求是「所有 repository 都用同一套自訂 query」，先嘗試中央設定檔；如果需求已經包含特殊 trigger、runner、permissions 或建置流程，才重新評估 advanced setup。不要把「需要排除一個資料夾」直接升級成整套 workflow 維護。

上線後的驗證清單#

• 先保存一個 repository 在套用 property 前的 scan 結果，作為對照。
• 檢查設定檔的 queries、paths 與 paths-ignore 是否真的符合每個語言與專案結構。
• 確認 private 設定檔的 Git Source private registry 已完成，且沒有把 token 放進 workflow。
• 列出有 explicit property 值的例外 repository，避免以為組織 rollout 已涵蓋全部。
• 把 CodeQL findings 與 GitHub Code Quality 的導入與成本 分開追蹤；前者是掃描設定，後者還包含 active committer、AI credits 與 rulesets。

這次更新提供的是一個中間層：你可以維持 default setup，卻不用接受所有 repository 都只能使用相同預設值。先用單一 repository 驗證設定檔和 findings，再把 property 推廣到組織，會比一次修改所有掃描流程更容易回溯。

常見問題#