Community寫作與編輯github.com

Paldom/python-skills

用於維護高品質開源 Python 套件的代理技能與鉤子——涵蓋 linting、測試、打包、發佈與 CI 品質閘門的代理式工程設定。

python-skills 是什麼?

此技能旨在建立並維護一個強大的 GitHub Actions CI 品質閘門,適用於 Python 儲存庫。它能自動化建立包含 lint、型別檢查與多版本測試矩陣的工作流程,透過 `uv` 快取進行優化,並彙總至一個 `all-checks-passed` 作業作為唯一必要的狀態檢查。技能的核心重點在於強化 CI 管線,防止常見的弱化攻擊(例如跳過作業被視為成功、未引用的版本導致矩陣錯誤、使用可變的 Action 標籤,以及 `pull_request_target` 的權限提升問題),確保 CI 如同生產程式碼般受到重視且無法被繞過。它支援 `astral-sh/setup-uv` 與傳統的 pip 設定,並提供檢查未固定 Action、安全性漏洞與結構錯誤的腳本。此技能與負責發佈、pre-commit 設定、測試覆蓋率設定及供應鏈安全的其他技能明確分工,以維持明確的關注點分離。

相容平台✓Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add Paldom/python-skills

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 可寫入的快取視為有敵意的。

捆綁資源

相關技能