python-ci
目的
為 Python 儲存庫建立 GitHub Actions 品質閘門:一個工作流程,執行 lint、型別檢查,並在一個包含 uv 快取的 Python 版本矩陣上執行測試,彙總至一個 all-checks-passed 彙總作業,透過分支規則集強制執行必需的狀態檢查,並針對 CI 因常見方式(跳過但被計為成功的作業、重新命名導致 PR 擱置的矩陣分支、可變的 action 標籤、過於寬泛的 GITHUB_TOKEN 範圍、pull_request_target 以及快取信任邊界漏洞)而被暗自弱化的情況進行強化。CI 是唯一無法透過 --no-verify 繞過的強制執行層——將工作流程檔案本身視為生產程式碼。
何時不應使用
- 發佈/發布工作流程(標籤觸發的 PyPI 發布、受信任發布、版本提升)——如果已安裝,
python-release技能擁有這些。此技能僅確保發布作業可以needs:的品質閘門。 - pre-commit 設定或其 CI 鏡像作業——請使用
python-precommit技能。 - coverage.py 設定(
fail_under值、relative_files、來源路徑)——請使用python-testing技能。此技能僅透過工作流程(每個分支的產出物、合併作業的位置)連接覆蓋率。 - Dependabot、密碼掃描、CodeQL、Scorecard、SBOM、CODEOWNERS——請使用
python-supply-chain技能。 - 修復 CI 報告的失敗(lint 錯誤、型別錯誤、測試失敗)——請使用
python-lint/python-typing技能或進行一般除錯。
工作流程
1. 在編寫 YAML 之前調查儲存庫
- 讀取
pyproject.toml:設定了哪些工具([tool.ruff]、mypy/pyright/ty、pytest)、requires-python範圍(定義矩陣)以及相依性群組(dev或dependency-groups)。 - 檢查是否有已提交的
uv.lock。如果有,CI 必須使用uv sync --locked——永遠不要在執行器中重新產生 lockfile;lockfile 的變更應屬於提交。 - 列出現有的
.github/workflows/檔案;有目的地擴展或取代,並檢查儲存庫設定中是否有合併佇列(它們會改變觸發器集合——步驟 5)。 - CI 執行儲存庫已定義的內容。不要引入新工具或更寬鬆的變體:閘門必須執行開發人員在本機執行的相同命令,並使用檢查模式(
ruff check、ruff format --check)——如果先前層級已自動修復,CI 僅進行驗證。一個執行--fix的make check不得重複用作 CI 步驟。 - 在現有程式碼庫上首次執行 CI:先在本機執行 lint/type/test 命令。在從未 lint 過的儲存庫上啟用閘門會嚴重失敗;在啟用閘門之前,先進行一次清理提交(或將該工作移交給相關技能)。
2. 編寫品質閘門工作流程
建立 .github/workflows/ci.yml。包含覆蓋率和彙總作業的完整註解範本:references/ci-workflow-template.md。關鍵的選擇:
name: CI
on:
push:
branches: [main]
pull_request:
merge_group: # 沒有這個,合併佇列驗證會靜默地從不報告
permissions:
contents: read # 作業層級的區塊只在需要時才放寬此權限
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
- 作業:
lint(ruff check + format --check)、typecheck(儲存庫設定的任何檢查器)、test(跨矩陣的 pytest)。兩種有效的排序方式——選擇一種並說明原因:三個全部並行(最快的壁鐘回饋)或test: needs: lint(一個 10 秒的 lint 失敗會跳過昂貴的矩陣;當 lint 通過時回饋較慢)。對於小型套件,並行是更安全的預設值。 - 環境:
astral-sh/setup-uv搭配enable-cache: true和一個python-version: ${{ matrix.python-version }}輸入——不需要單獨的actions/setup-python。使用uv sync --locked --group dev安裝,使用uv run <tool>執行工具。(沒有 uv?actions/setup-python@v5搭配cache: pip加上pip install -e .[dev]和直接的工具命令是備用方案;說明一次即可。) - 矩陣:
requires-python中的每個版本,需用引號括起來——['3.10', '3.11', '3.12', '3.13']。未引號的3.10在 YAML 中代表浮點數3.1。關於fail-fast的決策規則:當你需要完整的跨版本信號時設為false(此處為預設值),僅在快速的 PR 循環中,當首次失敗就足夠時設為true。只有當套件執行平台相依工作時才使用 OS 軸;每個軸都會增加計費分鐘數(每個工作流程執行次數硬上限為 256 個作業)。 - 從第一個草稿開始,就將每個 action 固定到完整的提交 SHA(步驟 6),而不是在後續階段進行。
3. 透過矩陣連接覆蓋率(僅工作流程端)
如果儲存庫測量覆蓋率,逐個分支的閘門是錯誤的:跳過特定版本程式碼的分支即使合併後的覆蓋率沒問題也會失敗。
- 每個矩陣分支將其資料檔案上傳為產出物:包含矩陣值的唯一名稱(
coverage-${{ matrix.python-version }}),以及include-hidden-files: true,因為.coverage.*檔案是隱藏的。 - 一個
coverage作業(needs: test)下載所有分支,執行uv run coverage combine和uv run coverage report。閾值值和relative_files = true(跨執行器合併所需)存在於儲存庫的覆蓋率設定中——這是python-testing技能的領域;此技能僅在合併作業中放置閘門。 - 上傳到外部服務(Codecov 等)?從合併作業或一個規範分支上傳——每個分支都上傳會產生重複/衝突的報告。
4. 新增彙總作業——唯一必要的檢查
矩陣分支和作業名稱會變更;分支設定不會跟著它們變化。閘門應設定在一個穩定的作業上:
all-checks-passed:
runs-on: ubuntu-latest
needs: [lint, typecheck, test, coverage]
if: always() # 沒有這個,當相依項失敗時作業會被 SKIPPED——而跳過會被計為成功
steps:
- name: 如果任何需要的作業未成功則失敗
run: |
if [[ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" == "true" ]]; then
echo "::error::一個必要的作業失敗或已取消。"
exit 1
fi
echo "所有檢查已通過。"
- 如果
needs:中的任何作業從未被有意跳過,則也對contains(needs.*.result, 'skipped')進行失敗處理——一個設定錯誤的if:會因此浮現,而不是靜默通過。如果某些作業是路徑過濾的,則保持允許跳過狀態並記錄原因(請參閱參考資料中的路徑過濾變體)。 - 保持作業名稱穩定;重新命名它意味著在同一個 PR 中更新分支設定,否則無法合併。
5. 使其成為必要——規則集或分支保護
首先執行一次工作流程(推送一個分支 / 開啟一個測試 PR):檢查在它們至少報告一次之後才會出現在必要檢查選擇器中。
偏好規則集(可疊加、也可針對標籤、組織層級、「評估」預覽模式、精細的繞過角色);對於單一簡單的儲存庫,經典分支保護也足夠。透過 API 進行設定以避免漂移——經典方式:
gh api repos/{owner}/{repo}/branches/main/protection --method PUT \
--field required_status_checks='{"strict":true,"contexts":["all-checks-passed"]}' \
-F enforce_admins=true \
--field required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}' \
-F restrictions=null
- 僅將
all-checks-passed標記為必要。將個別的矩陣分支設為必要檢查會在每次矩陣變更時阻塞每個 PR(「等待報告狀態」)。 - 啟用「不允許繞過」/ 保持
enforce_admins開啟——否則管理員(或持有管理員 token 的代理)可以繞過所有檢查進行合併。 strict: true(分支必須是最新的)在一個繁忙的 main 分支上會造成一個基於 rebase 的無盡循環;合併佇列是結構性的解決方案。使用合併佇列時,工作流程必須在merge_group上觸發,並且必要檢查會在佇列時進行驗證。- 標籤保護(阻止重新標記發佈版本)是一個規則集功能;當儲存庫發佈產出物時,新增一個標籤規則集。
規則集 JSON、合併佇列細節,以及針對「PR 是綠色的但無法合併」的診斷手冊:references/required-checks-and-rulesets.md。
6. 強化工作流程
詳細資訊、理由和事件歷史:references/workflow-hardening.md。
-
將每個 action 固定到 SHA——可變的標籤會被重新指向(2025 年的 tj-actions 洩漏事件向每個
@v消費者提供了惡意程式碼)。解析標籤:git ls-remote https://github.com/astral-sh/setup-uv refs/tags/v5\* # `^{}` 行是註解標籤的提交 SHA——固定這個格式:
uses: owner/action@<40-hex-sha> # v5.4.1——保留版本註解;更新工具和人為操作都以此為依據。 -
最小化
GITHUB_TOKEN:工作流程層級permissions: contents: read,僅在需要時在作業層級新增。永遠不要依賴儲存庫範圍的預設值。 -
使用 zizmor 對工作流程進行靜態分析(範本注入、危險觸發器、過度權限),並固定版本:
uvx zizmor==1.9.0 .github/workflows/檢查 https://github.com/zizmorcore/zizmor 以取得當前版本,並有目的地更新固定版本。actionlint(PyPI:
actionlint-py,固定您驗證的版本)另外會捕獲格式化程式無法發現的結構/語法錯誤。 -
信任邊界:避免使用
pull_request_target,除非您完全理解它——與檢出 PR 程式碼或快取讀取/寫入結合,它是一個即時的秘密外洩和快取毒化向量。Actions 快取是按儲存庫命名空間共享的:永遠不要快取秘密,並將 fork PR 可寫入的快取視為對後續受信任作業的不可信任輸入。 -
執行
scripts/check_workflows.py(如下)以確定性地捕獲上述所有問題的回歸。
7. 端到端驗證
python3 "${CLAUDE_SKILL_DIR}/scripts/check_workflows.py" --repo . # 未固定的 action、浮點數版本、缺少 if: always()、...
uvx zizmor==1.9.0 .github/workflows/ # 安全性發現
git switch -c ci-setup && git push -u origin ci-setup
gh pr create --fill && gh pr checks --watch # 每個作業都綠燈,彙總器報告
然後確認 all-checks-passed 在分支規則中是可選且已選中的,並且——如果合併佇列已開啟——一個已排入佇列的 PR 確實能合併。
輸出規格——完成的樣子
.github/workflows/ci.yml:lint + typecheck + test-matrix + (coverage) +all-checks-passed,觸發器包含pull_request和merge_group,工作流程層級permissions: contents: read,PR 的並發取消,每個 action 都固定到 SHA 並帶有版本註解,引號內的矩陣版本,uv sync --locked。main上的分支規則集(或經典保護)僅要求all-checks-passed,包含管理員,開啟過期審查關閉。scripts/check_workflows.py和 zizmor 在最終樹上都退出代碼 0。- 一個完整執行綠色閘門的 PR——並且在 PR 描述中說明了閘門強制執行了什麼,以及作業重新命名必須在同一個 PR 中更新分支設定。
失敗模式與陷阱
| 症狀 / 風險 | 原因與修正 |
|---|---|
| PR 永遠「等待報告狀態」 | 必要檢查綁定到一個已重新命名/刪除的作業或矩陣分支。閘門設定在彙總器上;在同一個 PR 中更新設定和作業名稱。 |
| 彙總器是綠色的但作業失敗了 | 缺少 if: always()——作業被跳過,而跳過的必要檢查被計為成功。明確的結果檢查是關鍵的。 |
| 儘管 PR 檢查通過,合併佇列仍卡住 | 工作流程缺少 merge_group 觸發器,因此必要檢查在佇列時從不報告。 |
| 矩陣執行 Python 3.1 | 未引號的 3.10 被解析為浮點數。每個版本都用引號括起來。 |
| 一個失敗取消所有矩陣分支 | fail-fast 預設為 true;在除錯時或當完整的跨版本信號很重要時設為 false。 |
| 覆蓋率在一個分支上失敗,但總體沒問題 | 逐個分支的閾值強制執行。先合併,再進行一次閘門檢查,在合併作業中進行。 |
| 在設定中無法選擇必要檢查 | 它從未執行過。觸發工作流程一次(推送/PR),然後選擇它。 |
| 儘管所有檢查都通過,合併仍被阻塞 | 跨工作流程檔案的重複作業名稱會使檢查上下文不明確——保持作業名稱在儲存庫範圍內唯一。 |
| 代理的 PR 之後 CI 通過,但閘門變弱了 | 審查工作流程差異,檢查 || true、已刪除的步驟、放寬的觸發器、修改的閾值。伺服器端的必要檢查 + 管理員強制執行是本地代理無法繞過自身修改的唯一層級;對 .github/(供應鏈技能)的 CODEOWNERS 增加了審查。 |
| 機器人推送/標籤後工作流程未觸發 | 使用預設 GITHUB_TOKEN 建立的事件不會啟動新的工作流程執行——鏈接需要 GitHub App token 或 PAT(python-release 技能領域)。 |
| 在 Ruff 發佈後格式檢查立即失敗 | 工具版本必須來自 lockfile(uv sync --locked),以便 CI 和本機執行使用相同的版本——永遠不要在一個工作流程步驟中執行未固定的 pip install ruff。 |
| 透過 fork PR 進行快取毒化 | pull_request_target + 快取寫入是一條權限提升路徑。GitHub 一直在收緊低信任度事件的快取/token 語義(滾動變更——在 GitHub 的變更記錄中驗證當前行為);設計時將 fork 可寫入的快取視為有敵意的。 |
捆綁資源
- references/ci-workflow-template.md —— 完整的註解
ci.yml(矩陣、覆蓋率合併、彙總器)加上變體:needs:鏈接的作業、路徑過濾的彙總器、動態矩陣。 - references/required-checks-and-rulesets.md —— 彙總器模式選項、規則集 vs 經典保護、
gh api食譜、合併佇列、標籤規則集、阻塞合併的診斷手冊。 - references/workflow-hardening.md —— SHA 固定(以及 Dependabot 警報的取捨)、
GITHUB_TOKEN範圍設定、zizmor