CommunityRédaction et éditiongithub.com

python-ci

Construisez la passerelle de qualité GitHub Actions pour un dépôt Python : workflows de lint, vérification de type, et tests sur une matrice de versions Python avec mise en cache uv, un job agrégateur « all-checks-passed », et des mesures de durcissement contre les faiblesses silencieuses des CI.

Qu'est-ce que python-ci ?

Ce skill automatisé pour agents IA configure une passerelle de qualité CI/CD robuste pour les dépôts Python sur GitHub Actions. Il génère un workflow CI complet (lint, typecheck, tests matriciels, agrégateur de couverture et job « all-checks-passed ») qui sert de vérification obligatoire unique, évitant ainsi les pièges courants comme les jobs ignorés comptant comme succès ou les modifications de noms de jobs qui bloquent les PR. Le skill met l'accent sur le durcissement : épinglage SHA des actions, permissions minimales GITHUB_TOKEN, analyse statique des workflows avec zizmor, et protection contre les attaques de cache via fork. Il est conçu pour Claude Code et autres agents ingénierie, et s'appuie sur des templates de référence et des scripts de vérification (check_workflows.py) pour garantir que la passerelle reste fiable face aux régressions.

Compatible avec✓Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add Paldom/python-skills

Installed? Explore more Rédaction et édition skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 plage requires-python (elle définit la matrice), et les groupes de dépendances (dev ou dependency-groups).
  • Vérifier la présence d'un uv.lock commité. S'il est présent, la CI doit utiliser uv 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 commande make check qui exécute --fix ne 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) ou test: 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-uv avec enable-cache: true et une entrée python-version: ${{ matrix.python-version }} — pas besoin de actions/setup-python séparé. Installez avec uv sync --locked --group dev, exécutez les outils avec uv run <tool>. (Pas de uv ? actions/setup-python@v5 avec cache: pip plus pip 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.10 sans guillemets est YAML pour le flottant 3.1. Règle de décision pour fail-fast : false lorsque vous voulez un signal complet multi-version (défaut ici), true uniquement 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 }}), et include-hidden-files: true car les fichiers .coverage.* sont cachés.
  • Un job coverage (needs: test) télécharge toutes les branches, exécute uv run coverage combine et uv run coverage report. La valeur de seuil et relative_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 sur contains(needs.*.result, 'skipped') — un if: 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-passed comme 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_admins actif — 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 sur merge_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-ci
    

    Format : 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_TOKEN minimal : permissions: contents: read au 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_target sauf 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 incluent pull_request et merge_group, permissions: contents: read au 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 main nécessitant uniquement all-checks-passed, admins inclus, révocation des reviews obsolètes activée.
  • scripts/check_workflows.py et 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 / risqueCause & correctif
PR "en attente que le statut soit rapporté" pour toujoursVé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éussiLe 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.13.10 non entre guillemets analysé comme flottant. Mettez chaque version entre guillemets.
Un échec annule toutes les branches de la matricefail-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'ensembleApplication 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ètresElle 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éussiDes 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 faibleVérifiez les diffs du workflow pour `
Le workflow ne s'est pas déclenché après un push/tag botLes é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 RuffLes 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 forkpull_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.yml annoté complet (matrice, combinaison de couverture, agrégateur) plus variantes : jobs chaînés par needs:, 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, ...

Skills associés