AkiGarage/safe-public-github-release

Publication GitHub Publique Sécurisée

Règle Fondamentale

Protégez la confiance publique avant la rapidité. Préférez un instantané public propre, une PR/CI de branche de release, des artefacts de publication GitHub vérifiés, des sommes de contrôle et l'approbation explicite du mainteneur pour les opérations irréversibles.

Ne publiez jamais l'historique privé en place. Un dépôt qui a été créé comme un instantané public propre et maintenu privé uniquement pour le polissage final peut être rendu public après la dernière porte de vérification. Utilisez PyPI/TestPyPI uniquement lorsque la distribution de packages Python est réellement concernée.

Flux de Travail

1. Inspectez d'abord :
   • git status -sb, remotes, branche courante, tags et workflows pertinents.
   • Visibilité du dépôt public, branche par défaut, état des releases/tags et environnements GitHub avec gh.
   • Documentation existante mentionnant les chemins d'installation, publication, Homebrew, TestPyPI, PyPI, dépôts privés, chemins locaux ou fichiers de transfert.
2. Délimitez la surface publique :
   • La documentation publique et les métadonnées de package peuvent mentionner le propriétaire/dépôt public, le nom du package, les tags publics et les commandes d'installation officielles.
   • La documentation publique ne doit pas mentionner les noms de dépôts privés, les chemins d'accueil locaux, HANDOFF.md, CONTINUITY.md, .local, .codex, tokens, clés, transcriptions internes brutes ou instructions réservées au mainteneur, sauf si réécrites en tant que directives publiques.
   • Préférez les liens relatifs dans le README pour la documentation et les médias locaux du dépôt. Les URL absolues du propriétaire/dépôt GitHub sont acceptables dans les notes de version, mais dans le README, elles peuvent créer un couplage évitable avec le propriétaire et des faux positifs dans les vérifications de surface publique.
3. Préparez les portes de publication GitHub :
   • Construisez/testez localement avant toute mutation à distance.
   • Utilisez par défaut release/vX.Y.Z -> PR -> CI -> merge avant le taggage.
   • Exigez l'approbation visuelle du README rendu par GitHub par Aki avant le merge lorsque le README ou les fichiers README localisés changent.
   • Vérifiez les artefacts de Release avant le téléchargement : noms de fichiers attendus, métadonnées de version, somme de contrôle, contenu de l'archive et vérifications de signature/notarisation spécifiques à la plateforme le cas échéant.
   • Pour les artefacts .app macOS zippés, construisez l'archive sans métadonnées AppleDouble ou Finder. Préférez COPYFILE_DISABLE=1 zip ou une commande d'archive équivalente, et rejetez les archives contenant __MACOSX, .DS_Store ou ._* fichiers. Ces fichiers supplémentaires peuvent faire échouer la vérification d'une application signée après décompression.
   • Vérifiez toujours l'archive exacte qui sera téléchargée en l'extrayant dans un répertoire temporaire, en vérifiant les métadonnées de version de l'application/package et en exécutant la vérification de signature/notarisation pertinente sur la charge utile extraite.
4. Publiez la release GitHub dans cet ordre :
   • Re-fetch main, vérifiez que la dernière CI est verte et confirmez que l'arbre de travail local est propre.
   • Confirmez que le tag cible et la Release GitHub n'existent pas déjà.
   • Créez le tag sur le commit main vérifié.
   • Poussez le tag.
   • Créez les fichiers de somme de contrôle à partir des fichiers de téléchargement finaux en utilisant les noms de base orientés release, et non les chemins locaux comme dist/....
   • Créez la Release GitHub avec des notes intentionnelles et uniquement des artefacts intentionnels.
   • Téléchargez les fichiers de somme de contrôle lorsque c'est utile pour le type d'artefact, et incluez la somme de contrôle dans les notes de Release lorsqu'elle aide les utilisateurs à vérifier le téléchargement.
5. Vérifiez après la publication GitHub :
   • Le tag pointe vers le commit attendu.
   • La Release GitHub est visible à l'URL attendue.
   • Les artefacts et sommes de contrôle de la Release correspondent aux fichiers vérifiés localement.
   • Téléchargez les artefacts de Release publiés dans un répertoire temporaire et vérifiez-les à partir des copies téléchargées. Pour les archives avec somme de contrôle, exécutez shasum -a 256 -c <asset>.sha256 ; pour les zip .app macOS, décompressez l'artefact téléchargé et exécutez la version de l'application et les vérifications codesign --verify --strict --deep sur l'application extraite.
   • Le README/la documentation publique correspond à la version de la release en direct et aux noms des artefacts.

Sous-section Facultative PyPI / TestPyPI

Utilisez cette sous-section uniquement lorsque la release GitHub publie également un package Python, CLI ou un chemin d'installation uvx.

1. Assurez-vous que les environnements GitHub existent pour testpypi et pypi.
2. Gardez pypi derrière l'approbation du mainteneur.
3. Utilisez id-token: write et les éditeurs de confiance PyPI au lieu des tokens PyPI stockés.
4. Publiez dans cet ordre :
   • Workflow de construction uniquement à partir du tag prévu.
   • Archive de Release GitHub avec SHA256SUMS et attestations d'artefact.
   • Publication TestPyPI, puis test d'installation.
   • Publication PyPI uniquement après que TestPyPI montre que la version et le test d'installation passent.
   • Mise à jour de la documentation pour rendre le chemin d'installation en direct principal.
5. Vérifiez après la publication :
   • Le JSON PyPI/TestPyPI contient la version attendue.
   • uvx --from <package> <command> --help fonctionne.
   • Le re-téléchargement de la même version est bloqué par les vérifications de préparation.
   • Le README/la documentation publique correspond au chemin d'installation en direct.

Liste de Contrôle pour Instantané Public Uniquement GitHub

Utilisez ceci lorsque la cible est un dépôt GitHub ou une release d'application sans PyPI.

1. Gardez le dépôt privé jusqu'à ce que la porte finale soit passée. Si la cible publique est un dépôt déjà public distinct, ne copiez jamais l'historique privé dedans ; déplacez uniquement le contenu de l'instantané nettoyé.
2. Utilisez une branche de release et une PR par défaut pour les instantanés publics :
   • Créez ou mettez à jour release/vX.Y.Z dans le dépôt public.
   • Commitez l'instantané préparé et la documentation publique sur cette branche.
   • Ouvrez une PR dans main et laissez la CI y tourner.
   • Lorsque le README ou les documents de release changent, utilisez également readme-release-sync pour que la copie publique reste lisible, bilingue et alignée sur le comportement publié.
   • Donnez à Aki des liens README rendus par GitHub pour la PR/la branche et attendez l'approbation visuelle explicite avant le merge. Les aperçus Markdown locaux, les vues de fichiers bruts, les captures d'écran ou les vérifications de liens automatisés ne remplacent pas cette porte.
   • Fusionnez uniquement après que la CI est verte et que la vérification de surface publique a réussi.
   • Poussez directement sur main uniquement lorsqu'Aki demande explicitement de sauter la porte PR.
3. Vérifiez les fichiers suivis, pas seulement l'arbre de travail :
   • secrets, chemins locaux, noms de mainteneurs, anciens noms de dépôts privés, fichiers de transfert, archives générées et noms de produits obsolètes.
   • git ls-files pour les fichiers .mov, .mp4 accidentels, les sorties de build, les caches et les gros fichiers binaires.
4. Traitez les médias README comme faisant partie de la surface publique :
   • Les GIF en ligne sont le format de démo README GitHub le plus fiable ; gardez-les sous la limite pratique d'image/GIF de GitHub.
   • Les embeds <video> locaux dans le README et les liens d'aperçu MP4 locaux peuvent échouer ou ouvrir des pages d'aperçu de fichiers GitHub instables.
   • Mettez les démos MP4 facultatives dans les artefacts de Release GitHub uniquement lorsque cela est vraiment nécessaire, et supprimez-les ainsi que les références dans les notes de version si le produit n'en a pas besoin.
5. Avant de créer le tag ou la Release GitHub, re-fetch :
   • L'état de merge de la PR et le dernier statut CI sur main après le merge
   • git status -sb, git log --oneline -1, git tag --list et les artefacts de release actuels
   • Le README et les chemins d'images référencés via l'API de contenu GitHub lorsque le dépôt est déjà public
   • Le contenu des archives et les résultats de vérification des artefacts extraits pour chaque téléchargement binaire
6. Avant de basculer la visibilité, re-fetch :
   • gh repo view ... --json visibility,isPrivate,url,defaultBranchRef
   • Le dernier statut Actions pour la branche par défaut
   • Les artefacts de Release et les notes de version
   • Le README et les chemins d'images référencés via l'API de contenu GitHub
7. Basculez la visibilité uniquement après qu'Aki a explicitement dit de publier, puis vérifiez visibility=PUBLIC, la disponibilité de l'URL README publique, les artefacts de Release et un arbre de travail local propre.

Flux d'Instantané Propre Vers un Dépôt Public

Utilisez ce flux lorsqu'un dépôt privé/interne alimente un dépôt public distinct.

1. Terminez et validez la fonctionnalité dans le dépôt privé.
2. Créez un dossier d'instantané temporaire à partir d'une liste autorisée de fichiers publics.
3. Appliquez le nommage public et supprimez les surfaces uniquement privées dans l'instantané.
4. Vérifiez l'instantané pour les secrets, chemins privés, fichiers de transfert, anciens noms de produits, archives générées et gros fichiers accidentels.
5. Copiez l'instantané vérifié dans l'arbre de travail du dépôt public.
6. Créez ou basculez sur release/vX.Y.Z.
7. Mettez à jour le README public, le README localisé, le changelog, les métadonnées de version, les notes de projet de release et les références aux médias README sur cette branche.
8. Inspectez git diff, les liens des médias README, la parité bilingue, le libellé obsolète et les résultats de l'analyse de surface publique.
9. Exécutez les vérifications locales de build/test/package pertinentes.
10. Commitez les modifications de préparation de release sur release/vX.Y.Z et poussez la branche.
11. Ouvrez une PR dans main ; ne taguez pas et ne créez pas encore de Release GitHub.
12. Attendez la CI, corrigez les échecs sur la branche de release et réexécutez les vérifications.
13. Envoyez à Aki les URL README rendues par GitHub pour README.md et tous les fichiers README localisés sur la PR/la branche. Attendez l'approbation visuelle explicite que le README semble correct sur GitHub.
14. Fusionnez la PR uniquement après que la CI, les portes de vérification et l'approbation visuelle du README GitHub rendu par Aki sont toutes passées.
15. Re-fetch main et vérifiez que le commit fusionné est propre et vert.
16. Arrêtez-vous pour l'approbation d'Aki avant de créer vX.Y.Z, de télécharger des artefacts ou de créer/publier la Release GitHub.

Flux Sans Dépôt Public Existant

Utilisez cette route lorsque le projet n'a jamais eu de dépôt public.

1. Ne basculez pas le dépôt de travail privé/interne en public.
2. Créez un nouveau dépôt de publication propre et gardez-le d'abord privé.
3. Initialisez-le uniquement à partir de l'instantané public vérifié, pas de l'historique privé.
4. Utilisez dès le départ des noms de produits publics, des métadonnées de package, des fichiers README, une licence, un changelog, des notes de projet de release, des captures d'écran/GIF et des workflows.
5. Exécutez la même vérification de secrets/chemins privés/gros fichiers/surface publique sur les fichiers suivis.
6. Utilisez release/vX.Y.Z -> PR -> CI -> approbation visuelle README GitHub rendue par Aki -> merge, même si le dépôt est encore privé.
7. Créez le tag prévu et le projet de Release GitHub pendant que le dépôt est encore privé lorsque cela est possible, et vérifiez les artefacts/sommes de contrôle à cet endroit.
8. Arrêtez-vous pour l'approbation d'Aki avant de changer la visibilité.
9. Basculez la visibilité en public uniquement après la vérification finale, la CI verte, les artefacts de release intentionnels et l'approbation explicite d'Aki.
10. Après le basculement de visibilité, re-fetch et vérifiez la disponibilité du README public, les artefacts de Release, les tags, le dernier statut Actions et l'arbre de travail local propre.

Leçons Importantes

• Les définitions de workflows GitHub Actions sont prises à partir de la référence utilisée pour déclencher le workflow. Si un tag a été créé avant l'ajout d'une nouvelle entrée ou d'une nouvelle porte de workflow, le déclenchement à partir de cet ancien tag ne connaîtra pas la nouvelle entrée.
• Les futures releases devraient placer les portes de release avant de créer le tag. Déclenchez ensuite à partir de ce tag avec les entrées protégées.
• Si un tag historique ponctuel est antérieur à la porte, ne devinez pas. Exécutez des vérifications de préparation locales, prouvez d'abord TestPyPI, vérifiez les artefacts/attestations et documentez l'exception.
• L'hygiène des artefacts de Release compte : après des téléchargements exploratoires, la Release publique finale ne doit contenir que des artefacts intentionnels. Supprimez les artefacts indésirables et retirez leurs lignes SHA ou leurs mentions dans les notes de version avant de publier.

Runbook Détaillé

Lisez references/pypi-trusted-release-runbook.md pour la liste de contrôle étape par étape, les modèles de commandes et les modèles d'audit de documentation publique.