Que fait python-ci ?
Objectif
Construire la passerelle de qualité GitHub Actions pour un dépôt Python : des workflows qui exécutent lint, vérification de type et tests sur une matrice de versions Python avec mise en cache uv, convergent vers un job agrégateur all-checks-passed, sont imposés comme vérifications de statut requises via des règles de branche, et sont durcis contre les faiblesses silencieuses des CI (jobs ignorés qui comptent comme succès, branches de matrice renommées qui bloquent les PR, tags d'action mutables, permissions trop larges de GITHUB_TOKEN, failles de confiance pull_request_target et de cache). La CI est la seule couche d'application qui ne peut être contournée avec --no-verify — traitez les fichiers de workflow comme du code de production.
Quand NE PAS utiliser
- Workflows de release/publication (publication PyPI déclenchée par tag, publication de confiance, incrémentation de version) — le skill python-release, s'il est installé, les possède. Ce skill assure seulement la passerelle de qualité sur laquelle un job de publication peut s'appuyer avec
needs:. - Configuration pre-commit ou son job miroir CI — le skill python-precommit.
- Configuration de coverage.py (valeurs
fail_under,relative_files, chemins source) — le skill python-testing. Ce skill ne fait que câbler la couverture à travers le workflow (artefacts par branche, placement du job de combinaison). - Dependabot, secret scanning, CodeQL, Scorecard, SBOMs, CODEOWNERS — le skill python-supply-chain.
- Correction des échecs signalés par CI (erreurs de lint, erreurs de type, tests échoués) — les skills python-lint / python-typing ou débogage ordinaire.
Workflow
1. Examiner le dépôt avant d'écrire du YAML
- Lire
pyproject.toml: quels outils sont configurés ([tool.ruff], mypy/pyright/ty, pytest), la plagerequires-python(elle définit la matrice), et les groupes de dépendances (devoudependency-groups). - Vérifier la présence d'un
uv.lockcommité. S'il est présent, la CI doit utiliseruv sync --locked— ne jamais régénérer le fichier de verrouillage dans le runner ; les modifications du lockfile appartiennent aux commits. - Lister les fichiers
.github/workflows/existants ; les étendre ou les remplacer délibérément, et vérifier les paramètres du dépôt pour les files d'attente de fusion (elles changent l'ensemble des déclencheurs — étape 5). - La CI exécute ce que le dépôt définit déjà. N'introduisez pas de nouveaux outils ou de variantes plus lâches : la passerelle doit exécuter les mêmes commandes que les développeurs exécutent localement, en mode vérification (
ruff check,ruff format --check) — si une couche antérieure corrige automatiquement, la CI ne fait que vérifier. Une commandemake checkqui exécute--fixne doit pas être réutilisée comme étape CI. - Premier lancement CI sur une base de code existante : exécutez d'abord les commandes lint/type/test localement. Activer des passerelles sur un dépôt jamais linté échoue durement ; réalisez un commit de nettoyage (ou confiez-le au skill concerné) avant d'activer la passerelle.
2. Créer le workflow de passerelle qualité
Créez .github/workflows/ci.yml. Modèle complet annoté avec les jobs de couverture et d'agrégation câblés : references/ci-workflow-template.md. Les choix structurants :
name: CI
on:
push:
branches: [main]
pull_request:
merge_group: # sans cela, la validation de la file d'attente de fusion ne signale jamais silencieusement
permissions:
contents: read # les blocages au niveau job élargissent cela uniquement là où nécessaire
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
- Jobs :
lint(ruff check + format --check),typecheck(le vérificateur configuré dans le dépôt),test(pytest sur la matrice). Deux ordonnancements valides — choisissez-en un et justifiez-le : les trois en parallèle (retour wall-clock le plus rapide) outest: needs: lint(un échec de lint de 10 secondes évite la matrice coûteuse ; retour plus lent lorsque le lint passe). Le parallèle est le défaut le plus sûr pour les petites suites. - Environnement :
astral-sh/setup-uvavecenable-cache: trueet une entréepython-version: ${{ matrix.python-version }}— pas besoin deactions/setup-pythonséparé. Installez avecuv sync --locked --group dev, exécutez les outils avecuv run <tool>. (Pas de uv ?actions/setup-python@v5aveccache: pippluspip install -e .[dev]et des commandes d'outils directes est le fallback ; indiquez-le une fois et passez à autre chose.) - Matrice : chaque version dans
requires-python, entre guillemets —['3.10', '3.11', '3.12', '3.13'].3.10sans guillemets est YAML pour le flottant3.1. Règle de décision pourfail-fast:falselorsque vous voulez un signal complet multi-version (défaut ici),trueuniquement pour les boucles PR rapides où le premier échec suffit. Axe OS uniquement si le package fait du travail dépendant de la plateforme ; chaque axe multiplie les minutes facturées (limite dure de 256 jobs par exécution de workflow). - Épinglez chaque action à un SHA de commit complet (étape 6) dès la première ébauche, pas comme passe ultérieure.
3. Câbler la couverture à travers la matrice (côté workflow uniquement)
Si le dépôt mesure la couverture, l'application par branche est erronée : une branche qui ignore du code spécifique à une version échoue même si la couverture combinée est bonne.
- Chaque branche de la matrice télécharge son fichier de données comme artefact : nom unique incluant les valeurs de la matrice (
coverage-${{ matrix.python-version }}), etinclude-hidden-files: truecar les fichiers.coverage.*sont cachés. - Un job
coverage(needs: test) télécharge toutes les branches, exécuteuv run coverage combineetuv run coverage report. La valeur de seuil etrelative_files = true(nécessaire pour la combinaison multi-runner) vivent dans la configuration de couverture du dépôt — territoire de python-testing ; ce skill ne fait que placer la passerelle dans le job de combinaison. - Téléchargement vers un service externe (Codecov etc.) ? Téléchargez depuis le job de combinaison ou une branche canonique — les téléchargements depuis chaque branche produisent des rapports en double/conflictuels.
4. Ajouter le job agrégateur — la seule vérification requise
Les branches de matrice et les noms de jobs changent ; les paramètres de branche ne les suivent pas. Passez par un job stable :
all-checks-passed:
runs-on: ubuntu-latest
needs: [lint, typecheck, test, coverage]
if: always() # sans cela, le job est IGNORÉ quand une dépendance échoue — et ignoré compte comme succès
steps:
- name: Échouer si un job nécessaire n'a pas réussi
run: |
if [[ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" == "true" ]]; then
echo "::error::Un job requis a échoué ou a été annulé."
exit 1
fi
echo "Toutes les vérifications ont réussi."
- Si aucun job dans
needs:n'est jamais intentionnellement ignoré, échouez aussi surcontains(needs.*.result, 'skipped')— unif:mal configuré apparaît alors au lieu de passer silencieusement. Si certains jobs sont filtrés par chemin, gardez l'ignoré autorisé et documentez pourquoi (voir la référence pour la variante de filtre par chemin). - Gardez le nom du job stable ; le renommer signifie mettre à jour les paramètres de branche dans la même PR ou rien ne fusionne.
5. Rendre la vérification obligatoire — rulesets ou protection de branche
Exécutez d'abord le workflow une fois (poussez une branche / ouvrez une PR de test) : les vérifications n'apparaissent dans le sélecteur de vérifications requises qu'après avoir été rapportées au moins une fois.
Préférez les rulesets (empilables, ciblent aussi les tags, au niveau org, mode "Évaluer" preview, acteurs de contournement granulaires) ; la protection de branche classique convient pour un seul dépôt simple. Configurez via l'API pour éviter la dérive — classique :
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
- Marquez uniquement
all-checks-passedcomme requis. Des branches de matrice individuelles comme vérifications requises bloquent chaque PR dès que la matrice change ("en attente que le statut soit rapporté"). - Activez "ne pas autoriser le contournement" / gardez
enforce_adminsactif — sinon un admin (ou un agent détenant un token admin) fusionne en contournant toutes les vérifications. strict: true(la branche doit être à jour) sur un main actif crée un tapis roulant de rebase ; une file d'attente de fusion est la solution structurelle. Avec une file d'attente de fusion, le workflow doit se déclencher surmerge_group, et les vérifications requises sont validées au moment de la mise en file d'attente.- La protection des tags (bloquer le re-tagging des releases) est une fonctionnalité des rulesets ; ajoutez un ruleset de tag lorsque le dépôt publie des artefacts.
JSON de ruleset, spécificités de la file d'attente de fusion, et un playbook de diagnostic pour "la PR est verte mais ne fusionne pas" : references/required-checks-and-rulesets.md.
6. Durcir les workflows
Détails, justification et historique des incidents : references/workflow-hardening.md.
-
Épinglez chaque action par SHA — les tags mutables sont repointés (la compromission tj-actions 2025 a livré du code malveillant à chaque consommateur
@v). Résolvez les tags :git ls-remote https://github.com/astral-sh/setup-uv refs/tags/v5\* # la ligne `^{}` est le SHA de commit pour les tags annotés — épinglez celle-ciFormat :
uses: owner/action@<40-hex-sha> # v5.4.1— gardez le commentaire de version ; les outils de mise à jour et les humains s'y réfèrent tous. -
GITHUB_TOKENminimal :permissions: contents: readau niveau workflow, ajouts au niveau job uniquement là où nécessaire. Ne vous fiez jamais à la valeur par défaut à l'échelle du dépôt. -
Analysez statiquement les workflows avec zizmor (injection de template, déclencheurs dangereux, permissions excessives), épinglé :
uvx zizmor==1.9.0 .github/workflows/Vérifiez https://github.com/zizmorcore/zizmor pour la version actuelle et mettez à jour l'épingle délibérément. actionlint (PyPI :
actionlint-py, épinglez la release que vous vérifiez) capture en plus les erreurs structurelles/syntaxiques qu'un formateur ne détecte pas. -
Frontières de confiance : évitez
pull_request_targetsauf si vous le comprenez pleinement — combiné avec le checkout du code PR ou la lecture/écriture de cache, c'est un vecteur d'exfiltration de secrets en direct et d'empoisonnement de cache. Les caches Actions sont partagés par espace de noms repo : ne cachez jamais de secrets, et traitez les caches inscriptibles par fork PR comme une entrée non fiable pour des jobs de confiance ultérieurs. -
Exécutez
scripts/check_workflows.py(ci-dessous) pour détecter les régressions dans tout ce qui précède de manière déterministe.
7. Vérifier de bout en bout
python3 "${CLAUDE_SKILL_DIR}/scripts/check_workflows.py" --repo . # actions non épinglées, versions flottantes, absence de if: always(), ...
uvx zizmor==1.9.0 .github/workflows/ # constats de sécurité
git switch -c ci-setup && git push -u origin ci-setup
gh pr create --fill && gh pr checks --watch # chaque job vert, agrégateur rapporte
Confirmez ensuite que all-checks-passed est sélectionnable et sélectionné dans les règles de branche, et — si une file d'attente de fusion est active — qu'une PR mise en file d'attente fusionne réellement.
Spécification de sortie — à quoi ressemble le travail terminé
.github/workflows/ci.yml: lint + typecheck + matrice de test + (couverture) +all-checks-passed, déclencheurs incluentpull_requestetmerge_group,permissions: contents: readau niveau workflow, annulation de concurrence pour les PR, chaque action épinglée par SHA avec un commentaire de version, versions de matrice entre guillemets,uv sync --locked.- Ruleset de branche (ou protection classique) sur
mainnécessitant uniquementall-checks-passed, admins inclus, révocation des reviews obsolètes activée. scripts/check_workflows.pyet zizmor sortent tous deux avec un code 0 sur l'arbre final.- Une PR qui a exécuté la passerelle complète en vert — et, déclaré dans la description de la PR, ce que la passerelle applique et que les renommages de jobs doivent mettre à jour les paramètres de branche dans la même PR.
Modes d'échec et pièges
| Symptôme / risque | Cause & correctif |
|---|---|
| PR "en attente que le statut soit rapporté" pour toujours | Vérification requise liée à un job ou une branche de matrice renommé/supprimé. Passez par l'agrégateur ; mettez à jour les paramètres et le nom du job dans la même PR. |
| Agrégateur vert alors que des jobs ont échoué | Absence de if: always() — le job a été ignoré, et les vérifications requises ignorées comptent comme succès. La vérification explicite du résultat est structurante. |
| File d'attente de fusion bloquée alors que les vérifications PR ont réussi | Le workflow manque du déclencheur merge_group, donc la vérification requise n'est jamais rapportée au moment de la mise en file d'attente. |
| La matrice exécute Python 3.1 | 3.10 non entre guillemets analysé comme flottant. Mettez chaque version entre guillemets. |
| Un échec annule toutes les branches de la matrice | fail-fast par défaut à true ; mettez false lors du débogage ou lorsque le signal complet multi-version compte. |
| La couverture échoue sur une branche, OK dans l'ensemble | Application du seuil par branche. Combinez d'abord, passez une fois, dans le job de combinaison. |
| La vérification requise ne peut pas être sélectionnée dans les paramètres | Elle n'a jamais été exécutée. Déclenchez le workflow une fois (push/PR), puis sélectionnez-la. |
| Les fusions sont bloquées alors que tout a réussi | Des noms de jobs en double dans les fichiers de workflow rendent le contexte de vérification ambigu — gardez les noms de jobs uniques à l'échelle du dépôt. |
| La CI réussit après une PR d'un agent, la passerelle est plus faible | Vérifiez les diffs du workflow pour ` |
| Le workflow ne s'est pas déclenché après un push/tag bot | Les événements créés avec le GITHUB_TOKEN par défaut ne démarrent pas de nouvelles exécutions de workflow — le chaînage nécessite un token d'application GitHub ou PAT (territoire python-release). |
| La vérification de format échoue juste après une release Ruff | Les versions des outils doivent provenir du lockfile (uv sync --locked), donc CI et exécutions locales utilisent des versions identiques — jamais pip install ruff non épinglé dans une étape de workflow. |
| Empoisonnement du cache via les PR fork | pull_request_target + écriture de cache est un chemin d'escalade. GitHub resserre les sémantiques cache/token pour les événements de faible confiance (changements continus — vérifiez le comportement actuel dans le changelog GitHub) ; concevez comme si les caches inscriptibles par fork sont hostiles. |
Ressources fournies
- references/ci-workflow-template.md —
ci.ymlannoté complet (matrice, combinaison de couverture, agrégateur) plus variantes : jobs chaînés parneeds:, agrégateur filtré par chemin, matrice dynamique. - references/required-checks-and-rulesets.md — options de motif agrégateur, rulesets vs protection classique, recettes
gh api, files d'attente de fusion, rulesets de tag, playbook de diagnostic de blocage de fusion. - references/workflow-hardening.md — épinglage SHA (et le compromis des alertes Dependabot), cadrage de
GITHUB_TOKEN, zizmor, ...