AkiGarage/safe-public-github-release

Sicheres öffentliches GitHub-Release

Kernregel

Schütze öffentliches Vertrauen vor Geschwindigkeit. Bevorzuge einen sauberen öffentlichen Snapshot, einen Release-Branch-PR/CI-Gate, verifizierte GitHub-Release-Artefakte, Prüfsummen und explizite Zustimmung des Maintainers für irreversible Operationen.

Veröffentliche niemals aus privater History an Ort und Stelle. Ein Repository, das als sauberer öffentlicher Snapshot erstellt und nur für die finale Nachbearbeitung privat gehalten wurde, darf nach der finalen Scrub-Prüfung auf öffentlich umgestellt werden. Verwende PyPI/TestPyPI nur, wenn die Verteilung von Python-Paketen tatsächlich im Scope liegt.

Arbeitsablauf

1. Zuerst inspizieren:
   • git status -sb, Remotes, aktueller Branch, Tags und relevante Workflows.
   • Öffentliche Repo-Sichtbarkeit, Standard-Branch, Release/Tag-Status und GitHub-Umgebungen mit gh.
   • Vorhandene Dokumente, die Installationspfade, Veröffentlichung, Homebrew, TestPyPI, PyPI, private Repos, lokale Pfade oder Übergabedateien erwähnen.
2. Öffentliche Oberfläche eingrenzen:
   • Öffentliche Dokumente und Paketmetadaten dürfen den öffentlichen Owner/Repo, Paketnamen, öffentliche Tags und offizielle Installationsbefehle erwähnen.
   • Öffentliche Dokumente dürfen keine privaten Repo-Namen, lokalen Home-Pfade, HANDOFF.md, CONTINUITY.md, .local, .codex, Tokens, Schlüssel, rohe interne Transkripte oder Maintainer-Anweisungen enthalten, es sei denn, sie werden als öffentlichkeitsorientierte Anleitung umgeschrieben.
   • Bevorzuge relative README-Links für repo-lokale Dokumente und Medien. Absolute GitHub Owner/Repo-URLs sind in Release-Notes in Ordnung, aber in der README können sie vermeidbare Owner-Kopplung und falsch positive Ergebnisse bei der Prüfung der öffentlichen Oberfläche verursachen.
3. GitHub-Release-Gates vorbereiten:
   • Vor Remote-Mutation lokal bauen/testen.
   • Standardmäßig release/vX.Y.Z -> PR -> CI -> Merge vor dem Tagging verwenden.
   • Akis visuelle GitHub-READER-Freigabe vor dem Merge anfordern, wenn README oder lokalisierte README-Dateien geändert werden.
   • Release-Assets vor dem Upload verifizieren: erwartete Dateinamen, Versionsmetadaten, Prüfsumme, Archivinhalt sowie ggf. plattformspezifische Signatur-/Notarisierungsprüfungen.
   • Bei macOS .app Zip-Assets das Archiv ohne AppleDouble oder Finder-Metadaten erstellen. Bevorzuge COPYFILE_DISABLE=1 zip oder einen äquivalenten Archivbefehl und lehne Archive ab, die __MACOSX, .DS_Store oder ._* Dateien enthalten. Diese zusätzlichen Dateien können dazu führen, dass eine signierte App nach dem Entpacken die Verifizierung nicht besteht.
   • Überprüfe immer das genaue Archiv, das hochgeladen wird, indem du es in ein temporäres Verzeichnis extrahierst, die App/Paket-Versionsmetadaten überprüfst und die relevante Signatur-/Notarisierungsverifizierung für die extrahierte Nutzlast durchführst.
4. GitHub-Release in dieser Reihenfolge veröffentlichen:
   • main neu abrufen, prüfen, ob das letzte CI grün ist, und bestätigen, dass der lokale Arbeitsbaum sauber ist.
   • Bestätigen, dass der Ziel-Tag und das GitHub-Release noch nicht existieren.
   • Tag auf dem verifizierten main-Commit erstellen.
   • Tag pushen.
   • Prüfsummendateien aus den endgültigen Upload-Dateien mit release-bezogenen Basisnamen (nicht lokalen Pfaden wie dist/...) erstellen.
   • GitHub-Release mit aussagekräftigen Notizen und nur den beabsichtigten Assets erstellen.
   • Prüfsummendateien hochladen, wenn sie für den Asset-Typ nützlich sind, und die Prüfsumme in die Release-Notes aufnehmen, wenn sie Benutzern hilft, den Download zu verifizieren.
5. Nach der GitHub-Veröffentlichung verifizieren:
   • Der Tag zeigt auf den erwarteten Commit.
   • Das GitHub-Release ist unter der erwarteten URL sichtbar.
   • Release-Assets und Prüfsummen stimmen mit den lokal verifizierten Dateien überein.
   • Die veröffentlichten Release-Assets in ein temporäres Verzeichnis herunterladen und anhand der heruntergeladenen Kopien verifizieren. Bei prüfsummengestützten Archiven shasum -a 256 -c <asset>.sha256 ausführen; bei macOS .app Zips das heruntergeladene Asset entpacken und App-Version sowie codesign --verify --strict --deep Prüfungen an der extrahierten App durchführen.
   • Öffentliche README/Dokumente stimmen mit der Live-Release-Version und den Asset-Namen überein.

Optionaler PyPI / TestPyPI Unterabschnitt

Diesen Unterabschnitt nur verwenden, wenn das GitHub-Release auch ein Python-Paket, CLI oder uvx-Installationspfad veröffentlicht.

1. Sicherstellen, dass GitHub-Umgebungen für testpypi und pypi existieren.
2. pypi hinter der Zustimmung des Maintainers halten.
3. id-token: write und PyPI Trusted Publishers anstelle von gespeicherten PyPI-Tokens verwenden.
4. In dieser Reihenfolge veröffentlichen:
   • Build-only-Workflow vom beabsichtigten Tag.
   • GitHub-Release-Archiv mit SHA256SUMS und Artefakt-Attestierungen.
   • TestPyPI veröffentlichen, dann install smoke.
   • PyPI erst veröffentlichen, nachdem TestPyPI die Version und den install smoke bestanden hat.
   • Dokumente aktualisieren, um den Live-Installationspfad primär zu machen.
5. Nach der Veröffentlichung verifizieren:
   • PyPI/TestPyPI JSON enthält die erwartete Version.
   • uvx --from <package> <command> --help funktioniert.
   • Erneutes Hochladen derselben Version wird durch Bereitschaftsprüfungen blockiert.
   • Öffentliche README/Dokumente stimmen mit dem Live-Installationspfad überein.

Nur-GitHub-Öffentlicher-Snapshot-Checkliste

Diese verwenden, wenn das Ziel ein GitHub-Repository oder App-Release ohne PyPI ist.

1. Das Repo bis zum finalen Gate privat halten. Wenn das öffentliche Ziel ein separates, bereits öffentliches Repository ist, niemals private History hineinkopieren; nur den gescrubbten Snapshot-Inhalt verschieben.
2. Standardmäßig einen Release-Branch und PR für öffentliche Snapshots verwenden:
   • release/vX.Y.Z im öffentlichen Repository erstellen oder aktualisieren.
   • Vorbereiteten Snapshot und öffentliche Dokumente auf diesem Branch committen.
   • PR in main eröffnen und CI dort laufen lassen.
   • Wenn README oder release-bezogene Dokumente geändert werden, auch readme-release-sync verwenden, damit die öffentliche Kopie lesbar, zweisprachig und auf das ausgelieferte Verhalten abgestimmt bleibt.
   • Aki GitHub-gerenderte README-Links für den PR/Branch geben und auf explizite visuelle Zustimmung vor dem Merge warten. Lokale Markdown-Vorschauen, Rohdateiansichten, Screenshots oder automatisierte Linkprüfungen ersetzen dieses Gate nicht.
   • Erst mergen, wenn CI grün ist und die Prüfung der öffentlichen Oberfläche bestanden wurde.
   • Nur direkt auf main pushen, wenn Aki explizit darum bittet, das PR-Gate zu überspringen.
3. Getrackte Dateien scruben, nicht nur den Arbeitsbaum:
   • Geheimnisse, lokale Pfade, Maintainer-Namen, alte private Repo-Namen, Übergabedateien, generierte Archive und veraltete Produktnamen.
   • git ls-files auf versehentliche .mov, .mp4, Build-Ausgaben, Caches und große Binärdateien.
4. README-Medien als Teil der öffentlichen Oberfläche behandeln:
   • Inline-GIFs sind das zuverlässigste GitHub-README-Demo-Format; halte sie unter GitHub's praktischem Bild/GIF-Limit.
   • Lokale README <video> Einbettungen und repo-lokale MP4-Vorschau-Links können fehlschlagen oder instabile GitHub-Dateivorschau-Seiten öffnen.
   • Optionale MP4-Demos nur dann in GitHub-Release-Assets ablegen, wenn sie wirklich benötigt werden, und sie sowie Release-Notes-Referenzen entfernen, wenn das Produkt sie nicht braucht.
5. Vor dem Erstellen des Tags oder GitHub-Releases neu abrufen:
   • PR-Merge-Status und aktuellen CI-Status auf main nach dem Merge
   • git status -sb, git log --oneline -1, git tag --list und aktuelle Release-Assets
   • README und referenzierte Bildpfade über die GitHub Contents API, wenn das Repository bereits öffentlich ist
   • Archivinhalte und Verifikationsergebnisse für extrahierte Assets für jeden Binär-Upload
6. Vor dem Umschalten der Sichtbarkeit neu abrufen:
   • gh repo view ... --json visibility,isPrivate,url,defaultBranchRef
   • letzten Actions-Status für den Standard-Branch
   • Release-Assets und Release-Notes
   • README und referenzierte Bildpfade über die GitHub Contents API
7. Sichtbarkeit erst umschalten, nachdem Aki explizit gesagt hat, zu veröffentlichen; dann visibility=PUBLIC, Verfügbarkeit der öffentlichen README-URL, Release-Assets und einen sauberen lokalen Arbeitsbaum verifizieren.

Clean Snapshot zu öffentlichem Repo Ablauf

Diesen Ablauf verwenden, wenn ein privates/internes Repository ein separates öffentliches Repository speist.

1. Feature im privaten Repository abschließen und validieren.
2. Temporären Snapshot-Ordner aus einer Allowlist öffentlicher Dateien erstellen.
3. Öffentliche Benennung anwenden und private-only Oberflächen im Snapshot entfernen.
4. Snapshot auf Geheimnisse, private Pfade, Übergabedateien, alte Produktnamen, generierte Archive und große versehentliche Dateien scruben.
5. Gescrubbten Snapshot in den Arbeitsbaum des öffentlichen Repositorys kopieren.
6. release/vX.Y.Z erstellen oder zu diesem wechseln.
7. Öffentliche README, lokalisierte README, Changelog, Versionsmetadaten, Release-Entwurfsnotizen und README-Medienreferenzen auf diesem Branch aktualisieren.
8. git diff, README-Medienlinks, Zweisprachigkeit, veraltete Formulierungen und Ergebnisse der Prüfung der öffentlichen Oberfläche inspizieren.
9. Relevante lokale Build-/Test-/Paketprüfungen durchführen.
10. Release-Vorbereitungs-Änderungen auf release/vX.Y.Z committen und den Branch pushen.
11. PR in main eröffnen; noch keinen Tag oder kein GitHub-Release erstellen.
12. Auf CI warten, Fehler auf dem Release-Branch beheben und Prüfungen erneut durchführen.
13. Aki die GitHub-gerenderten README-URLs für README.md und alle lokalisierten README-Dateien auf dem PR/Branch senden. Auf explizite visuelle Zustimmung warten, dass die README auf GitHub korrekt aussieht.
14. PR erst mergen, nachdem CI, Scrub-Gates und Akis visuelle GitHub-READER-Freigabe alle bestanden sind.
15. main neu abrufen und überprüfen, ob der gemergte Commit sauber und grün ist.
16. Für Akis Zustimmung anhalten, bevor vX.Y.Z erstellt, Assets hochgeladen oder das GitHub-Release erstellt/veröffentlicht wird.

Noch kein öffentliches Repository Ablauf

Diesen Weg verwenden, wenn das Projekt noch nie ein öffentliches Repository hatte.

1. Das private/interne Arbeits-Repository nicht auf öffentlich umstellen.
2. Ein neues sauberes Veröffentlichungs-Repository erstellen und zunächst privat halten.
3. Es nur aus dem gescrubbten öffentlichen Snapshot initialisieren, nicht aus der privaten History.
4. Von Anfang an öffentlichkeitsorientierte Produktnamen, Paketmetadaten, README-Dateien, Lizenz, Changelog, Release-Entwurfsnotizen, Screenshots/GIFs und Workflows verwenden.
5. Dieselbe Scrub-Prüfung für Geheimnisse/private-Pfade/große-Dateien/öffentliche Oberfläche an getrackten Dateien durchführen.
6. release/vX.Y.Z -> PR -> CI -> Akis visuelle GitHub-READER-Freigabe -> Merge verwenden, auch wenn das Repository noch privat ist.
7. Den beabsichtigten Tag und GitHub-Release-Entwurf erstellen, solange das Repo noch privat ist, wenn möglich, und Assets/Checks dort verifizieren.
8. Für Akis Zustimmung anhalten, bevor die Sichtbarkeit geändert wird.
9. Sichtbarkeit erst auf öffentlich umstellen, nachdem finaler Scrub, grünes CI, beabsichtigte Release-Assets und explizite Zustimmung von Aki vorliegen.
10. Nach der Sichtbarkeitsumstellung die Verfügbarkeit der öffentlichen README, Release-Assets, Tags, letzten Actions-Status und des sauberen lokalen Arbeitsbaums neu abrufen und verifizieren.

Wichtige Lektionen

• GitHub Actions Workflow-Definitionen werden aus der Ref genommen, die zum Auslösen des Workflows verwendet wird. Wenn ein Tag erstellt wurde, bevor eine neue Workflow-Eingabe oder ein neues Gate hinzugefügt wurde, weiß das Auslösen von diesem alten Tag nichts über die neue Eingabe.
• Zukünftige Releases sollten Release-Gates vor dem Erstellen des Tags platzieren. Dann von diesem Tag mit den geschützten Eingaben auslösen.
• Wenn ein einmaliger historischer Tag älter ist als das Gate, nicht raten. Lokale Bereitschaftsprüfungen durchführen, zuerst TestPyPI beweisen, Artefakte/Attestierungen verifizieren und die Ausnahme dokumentieren.
• Release-Asset-Hygiene ist wichtig: Nach explorativen Uploads sollte das finale öffentliche Release nur beabsichtigte Artefakte enthalten. Unerwünschte Assets löschen und ihre SHA-Zeilen oder Release-Notes-Erwähnungen vor der Veröffentlichung entfernen.

Detailliertes Runbook

Lies references/pypi-trusted-release-runbook.md für die Schritt-für-Schritt-Checkliste, Befehlsmuster und öffentliche-Dokument-Prüfmuster.