GitHub 在 2026 年 11 月 13 日宣布,AI Scan for repositories 的啟用狀態可由 REST API 管理。組織擁有者與 security manager 能在組織層設定,repository administrator 則可處理個別儲存庫;新增的 repository_scan 欄位可和既有的 pr_scan 一起讀取或更新。這讓團隊能用腳本或基礎設施設定批次管理,不必逐一進入每個 repository 的設定頁。
這項更新不代表「開啟後每次 push 都會自動掃描」。官方文件明確指出,repository backlog 的 AI Scan 仍是手動按需執行,只分析 default branch,且每次掃描會消耗 Code Security AI credits。新 API 管的是能否使用功能,不是排程執行掃描;若把兩者混在一起,可能出現設定全部顯示 enabled,實際上卻沒有任何掃描結果的假安全感。
先分清楚三層控制與適用範圍
Enterprise policy 是最上層護欄。企業若未允許 AI Scan,組織或儲存庫嘗試啟用時會受到政策阻擋。組織層設為 disabled 時,下層 repository 不能自行開啟;組織層啟用後,repository 繼承設定,但管理員仍可讓特定 repository opt out。官方也說,同一個 request 若同時修改 pr_scan 與 repository_scan,其中一項被擋時整筆更新會回傳 422,兩項都不會變更,因此批次工具不能把部分成功當成全部成功。
可用資格也要先盤點。組織擁有的 public repositories 可使用;private 或 internal repositories 需要 GitHub Code Security 或 GitHub Advanced Security。GitHub Enterprise Server 目前不在這次公開預覽的支援範圍。個人帳號與組織帳號的可用條件及計費歸屬也不同,企業導入時應以實際 owner、visibility、plan 與 billing account 建立清單,不能只依 repository 名稱判斷。
API token 應採最小權限並分開讀寫。盤點狀態的 job 只需要讀取能力;真正變更設定的 GitHub App 或 fine-grained token 才給必要的 organization administration 或 repository administration write 權限。不要為了方便,把可寫入所有 repository 的 classic token 放進一般 CI。每次執行要保存 repository、舊值、新值、HTTP status、request ID 與政策阻擋原因,日後才能追查誰在何時改變安全設定。
AI Scan、CodeQL 與既有檢查怎麼分工
AI Scan 會在 default branch 上選擇程式碼進一步分析,結果進入既有 code scanning backlog,可沿用 assignment、security campaign、issue 與修復流程。它支援所有語言,也能補充 CodeQL 已支援語言的發現;但官方同時提醒,掃描不是窮盡式分析,可能產生不準確或重複的 findings。它不能取代 CodeQL、SAST、依賴漏洞掃描、secret scanning、測試與人工風險判讀中的任何一個單點控制。
較合適的組合是:CodeQL 維持可重現、可在 pull request 或排程執行的規則式檢查;AI Scan 用於週期性 backlog discovery、較少被既有規則涵蓋的語言,或高風險 repository 的補充探索;dependency 與 secret 工具繼續處理套件及憑證風險。若一開始就把 AI finding 設為所有團隊的阻擋條件,可能因公開預覽行為、誤報與處理量造成交付塞車。
公開預覽還有幾項營運限制:掃描需要手動觸發,不支援 push 或排程自動掃描;套用修正後不會自動再掃一次;只有修正變更到觸發 alert 的精確程式碼行時,alert 才可能自動關閉。團隊應把「重掃確認」與「無法自動關閉時的處置紀錄」放進漏洞流程,而不是只看 alert 數量是否下降。
成本護欄要在批次開啟之前完成
每次 repository scan 都使用 Code Security AI credits,與 active-committer license 是不同計費面向。若帳號有 Copilot entitlement 附帶的 AI credits,符合資格的用量會先由該額度扣抵;額度用完後才依計量與 budget 規則處理。GitHub 文件指出,hard budget 沒有剩餘額度時,AI Scan 無法產出 findings,直到管理員調高限制或新的 billing cycle 開始。
因此,導入順序應先確認 billing owner、included credits、目前 agentic autofix 用量與 Code Security AI Credits budget,再決定試點規模。AI usage 畫面會把 AI Scan 與 agentic autofix 彙總在 Advanced Security 的同一產品用量中,不能直接把總額全算成 AI Scan。若要精確追查 GitHub App 帶來的使用量,官方建議下載 usage report,再用 app_client_id 對照 App installation。
預算不只要有金額上限,也要有使用規則。可依 repository 風險分成高、中、低三層:處理登入、付款、個資與管理權限的高風險服務優先;內部工具與低變更專案降低頻率;封存、範例、fork 與生成產物 repository 預設排除。記錄每次掃描的目的、觸發者、credits、有效 findings、誤報與修復時間,四週後才能判斷增加覆蓋是否值得成本。
從 5 個 repository 試點到組織級導入
第一階段選 3 到 5 個技術棧、規模與風險不同的 repository。先建立目前 CodeQL、依賴與 secret alerts 基準,再開啟 repository_scan,各執行一次 AI Scan。安全負責人與程式 owner 共同判讀 findings,記錄是否重複、能否重現、修正是否合理,以及重新掃描能否證明問題已處理。
第二階段才建立批次程式。程式先用 GET 收集現況與 eligibility,輸出預計變更清單;經 owner 確認後再 PATCH。對 403、404 與 422 分別處理,不要無限重試。執行完成後再次 GET 驗證,並把未成功項目列入例外清單。公開預覽的 request schema 仍可能調整,API version、response validation 與回滾設定都要固定在程式中。
第三階段建立營運指標:每次掃描有效 findings 比例、重複與誤報比例、平均分流時間、逾期未處理數、credits 使用量,以及各 repository 最後掃描日。只有當試點能穩定處理 findings,才擴到下一批。若安全團隊沒有容量處理新增 backlog,先改善 ownership 與 SLA,比把所有 repository 一次開啟更實際。
這次 REST API 的價值在於讓 AI Scan 的政策可以被盤點、版本化與稽核,而不是自動把所有程式碼變安全。適合的導入方式是先設 enterprise 與預算護欄,再用少量高風險 repository 驗證訊號品質,最後才批次擴張。把 API 設定、實際掃描、finding 處理與成本監控分開管理,才能避免「全部 enabled」卻沒有可證明的風險改善。