gh action pypi publish
v1.12.2
Mit dieser Aktion können Sie Ihre Python-Distributionspakete im Verzeichnis dist/ auf PyPI hochladen. Dieser Text schlägt eine minimalistische Nutzungsübersicht vor. Eine detailliertere Anleitung finden Sie im PyPA-Leitfaden.
Wenn Sie Feedback zu bestimmten Aktionsversionen haben, hinterlassen Sie bitte Kommentare in den entsprechenden Ankündigungsdiskussionen pro Veröffentlichung.
master -Sonnenuntergang Die master -Branch-Version ist Sunset. Bitte ändern Sie die von Ihnen verwendete GitHub Action-Version von master auf release/v1 , verwenden Sie ein genaues Tag oder entscheiden Sie sich für die Verwendung eines vollständigen Git-Commit-SHA und Dependabot.
Notiz
Die vertrauenswürdige Veröffentlichung kann derzeit nicht aus einem wiederverwendbaren Workflow heraus verwendet werden. Es wird empfohlen, stattdessen einen nicht wiederverwendbaren Workflow zu erstellen, der einen Job enthält, der Ihren wiederverwendbaren Workflow aufruft, und dann den Schritt der vertrauenswürdigen Veröffentlichung von einem separaten Job innerhalb dieses nicht wiederverwendbaren Workflows aus auszuführen. Alternativ können Sie innerhalb des wiederverwendbaren Workflows weiterhin einen Benutzernamen/Token verwenden.
Notiz
Als vertrauenswürdiges Publishing wird manchmal die zugrunde liegende Technologie bezeichnet – OpenID Connect, kurz OIDC. Wenn Sie Hinweise auf „OIDC-Veröffentlichung“ im Zusammenhang mit PyPI sehen, beziehen sie sich darauf.
Dieses Beispiel springt direkt in die aktuelle Best Practice ein. Wenn Sie API-Tokens direkt oder einen weniger sicheren Benutzernamen und ein weniger sicheres Passwort verwenden möchten, lesen Sie, wie Sie Benutzernamen und Passwort angeben.
Diese Aktion unterstützt die vertrauenswürdige Veröffentlichungsimplementierung von PyPI, die eine Authentifizierung bei PyPI ohne manuell konfiguriertes API-Token oder Benutzername/Passwort-Kombination ermöglicht. Um mit dieser Aktion eine vertrauenswürdige Veröffentlichung durchzuführen, muss der Herausgeber Ihres Projekts bereits auf PyPI konfiguriert sein.
Um in den vertrauenswürdigen Veröffentlichungsfluss einzutreten, konfigurieren Sie den Job dieser Aktion mit der id-token: write und ohne expliziten Benutzernamen oder Passwort:
# .github/workflows/ci-cd.ymljobs: pypi-publish:name: Release auf PyPIruns-on hochladen: ubuntu-latestenvironment: name: pypi url: https://pypi.org/p/<your-pypi-project -name>Berechtigungen: id-token: write # WICHTIG: Diese Berechtigung ist für vertrauenswürdige Veröffentlichungen obligatorisch. Schritte:# Rufen Sie Ihre Distributionen hier ab. Name: Paket veröffentlichen Verteilungen an PyPI verwenden: pypa/gh-action-pypi-publish@release/v1
Notiz
Profi-Tipp: Anstatt Verzweigungszeiger wie unstable/v1 zu verwenden, pinnen Sie Versionen von Aktionen, die Sie verwenden, an getaggte Versionen oder sha1-Commit-IDs an. Dadurch werden Ihre Arbeitsabläufe sicherer und besser reproduzierbar und Sie bleiben vor plötzlichen und unangenehmen Überraschungen geschützt.
Es können auch andere Indizes verwendet werden, die vertrauenswürdige Veröffentlichungen unterstützen, wie z. B. TestPyPI:
- Name: Paketverteilungen auf TestPyPI veröffentlichen verwendet: pypa/gh-action-pypi-publish@release/v1 mit:repository-url: https://test.pypi.org/legacy/
(Vergessen Sie nicht, den Umgebungsnamen auf testpypi oder ähnliches zu aktualisieren!)
Notiz
Profi-Tipp: Legen Sie die Schreibberechtigung id-token: write nur in dem Job fest, der die Veröffentlichung durchführt, nicht global. Versuchen Sie außerdem, das Erstellen und Veröffentlichen zu trennen. Dadurch wird sichergestellt, dass Skripte, die in böswilliger Absicht in die Build- oder Testumgebung eingeschleust werden, nicht in der Lage sind, Berechtigungen zu erhöhen, während sie unbemerkt bleiben.
Ein häufiger Anwendungsfall besteht darin, Pakete nur bei einem getaggten Commit hochzuladen. Fügen Sie dazu dem Job einen Filter hinzu:
if: github.event_name == 'push' && getsWith(github.ref, 'refs/tags')
Wichtig
Die Unterstützung für das Generieren und Hochladen digitaler Bescheinigungen ist derzeit experimentell und nur auf Trusted Publishing-Flows mit PyPI oder TestPyPI beschränkt. Die Unterstützung für diese Funktion ist noch nicht stabil; Die unten beschriebenen Einstellungen und Verhaltensweisen können ohne vorherige Ankündigung geändert werden.
Notiz
Das Erstellen und Hochladen digitaler Bescheinigungen erfordert derzeit eine Authentifizierung bei einem vertrauenswürdigen Herausgeber.
Das Generieren signierter digitaler Bescheinigungen für alle Verteilungsdateien und das gemeinsame Hochladen aller Dateien ist jetzt standardmäßig für alle Projekte aktiviert, die Trusted Publishing verwenden. Um es zu deaktivieren, legen Sie attestations wie folgt fest:
mit: Bescheinigungen: falsch
Die Attestierungsobjekte werden mithilfe von Sigstore für jedes Verteilungspaket erstellt und mit der Identität signiert, die durch das OIDC-Token von GitHub bereitgestellt wird, das dem aktuellen Workflow zugeordnet ist. Dies bedeutet, dass sowohl die vertrauenswürdige Veröffentlichungsauthentifizierung als auch die Attestierungen an dieselbe Identität gebunden sind.
Diese GitHub-Aktion hat nichts mit dem Erstellen von Paketverteilungen zu tun. Benutzer sind dafür verantwortlich, Dists für den Upload vorzubereiten, indem sie sie vor dem Ausführen dieser Aktion im Ordner dist/ ablegen.
Wichtig
Da diese GitHub-Aktion Docker-basiert ist, kann sie nur innerhalb von GNU/Linux-basierten Jobs in GitHub Actions CI/CD-Workflows verwendet werden. Dies ist beabsichtigt und wird sich aufgrund einer Reihe von Überlegungen, auf die wir uns verlassen, wahrscheinlich nicht ändern.
Dies sollte jedoch nicht davon abgehalten werden, plattformspezifische Distributionspakete zu veröffentlichen. Es wird dringend empfohlen, die Jobs zum Erstellen der betriebssystemspezifischen Räder vom Veröffentlichungsjob zu trennen. Dies ermöglicht es, (1) genau dieselben Artefakte zu testen, die gerade auf PyPI hochgeladen werden sollen, (2) zu verhindern, dass parallele, nicht synchronisierte Jobs nur einen Teil der Dists asynchron veröffentlichen (für den Fall, dass ein Teil der Jobs fehlschlägt und andere erfolgreich sind). mit einer unvollständigen Veröffentlichung auf PyPI) und (3) einen atomaren Upload auf PyPI durchführen (wenn ein Teil der Dists auf PyPI angezeigt wird, verwenden Installationsprogramme wie pip diese Version für die Abhängigkeitsauflösung, dies kann jedoch zu Problemen führen Einige Umgebungen verwenden SDISTs, obwohl das Rad für deren Laufzeit noch nicht verfügbar ist.
Um diese Art der Orchestrierung zu implementieren, verwenden Sie bitte actions/upload-artifact und actions/download-artifact um die erstellten Dists über Phasen und Jobs hinweg zu teilen. Verwenden Sie dann die needs , um die Build-, Test- und Veröffentlichungsphasen zu ordnen.
Um optimale Ergebnisse zu erzielen, finden Sie heraus, welche Art von Workflow den spezifischen Anforderungen Ihres Projekts entspricht.
Sie könnten beispielsweise einen parallelen Job implementieren, der jedes Commit an TestPyPI oder Ihren eigenen Indexserver wie devpi weiterleitet. Dazu müssen Sie (1) einen benutzerdefinierten repository-url Wert angeben und (2) für jeden Upload eine eindeutige Versionsnummer generieren, damit kein Konflikt entsteht. Letzteres ist möglich, wenn Sie das Paket setuptools_scm verwenden, Sie können aber auch Ihre eigene Lösung basierend auf der Entfernung zum zuletzt getaggten Commit erfinden.
Sie müssen ein weiteres Token für einen separaten Host erstellen und es dann als GitHub-Repo-Geheimnis in einer in Ihrem Job verwendeten Umgebung speichern. Allerdings würde die Übergabe eines Passworts die geheimnislose vertrauenswürdige Veröffentlichung deaktivieren, daher ist es besser, sie stattdessen beim Veröffentlichen auf TestPyPI zu konfigurieren und nicht etwas Benutzerdefiniertes.
Der Aktionsaufruf würde in diesem Fall wie folgt aussehen:
- Name: Paket auf TestPyPI veröffentlichen
verwendet: pypa/gh-action-pypi-publish@release/v1
with:password: ${{ Secrets.TEST_PYPI_API_TOKEN }}repository-url: https://test.pypi.org/legacy/ Sie können das Standardzielverzeichnis von dist/ in ein beliebiges Verzeichnis Ihrer Wahl ändern. Der Aktionsaufruf würde nun wie folgt aussehen:
- Name: Paket auf PyPI veröffentlichen verwendet: pypa/gh-action-pypi-publish@release/v1 with:packages-dir: custom-dir/
Es wird empfohlen, twine check direkt nach der Erstellung Ihrer Dateien durchzuführen, aber auch vor dem Hochladen wird twine check durchgeführt. Sie können die Garnkontrolle auch deaktivieren mit:
mit: verify-metadata: false
Wenn Sie Veröffentlichungen von mehreren Orten aus veröffentlichen, kann es manchmal vorkommen, dass Ihr Workflow auf Rennbedingungen stößt. Zum Beispiel beim Veröffentlichen von mehreren CIs oder sogar beim Auslösen von Workflows mit denselben Schritten innerhalb von GitHub Actions CI/CD für verschiedene Ereignisse, die denselben übergeordneten Akt betreffen.
Um diesen Anwendungsfall zu erleichtern, können Sie die Einstellung skip-existing (standardmäßig deaktiviert) wie folgt verwenden:
mit: skip-existing: true
Notiz
Profi-Tipp: Vermeiden Sie die Aktivierung dieser Einstellung nach Möglichkeit. Wenn Sie Schritte zum Veröffentlichen sowohl auf PyPI als auch auf TestPyPI haben, sollten Sie erwägen, diese nur für Letzteres zu verwenden, da Ersteres bei Duplikaten lautstark fehlschlägt.
Manchmal kann twine upload fehlschlagen. Verwenden Sie zum Debuggen die verbose Einstellung wie folgt:
mit: ausführlich: wahr
Möglicherweise möchten Sie überprüfen, ob die Dateien auf PyPI automatisch per CI-Skript hochgeladen wurden. Es werden die SHA256-, MD5- und BLAKE2-256-Werte der hochzuladenden Dateien angezeigt.
with:print-hash: true
Der Standardwert für den Benutzernamen ist __token__ . Wenn Sie in einer benutzerdefinierten Registrierung veröffentlichen, die keine API-Token bereitstellt, wie z. B. devpi , müssen Sie möglicherweise ein benutzerdefiniertes Benutzername-Passwort-Paar angeben. So wird es gemacht.
with:user: guidopassword: ${{ Secrets.DEVPI_PASSWORD }} Das in ${{ secrets.DEVPI_PASSWORD }} verwendete Geheimnis muss auf der Umgebungsseite unter den Einstellungen Ihres Projekts auf GitHub erstellt werden. Siehe Erstellen und Verwenden von Geheimnissen.
In der Vergangenheit war beim Veröffentlichen auf PyPI die Verwendung der API-Token-Funktion von PyPI die sicherste Methode zur Festlegung des Zugriffsbereichs für die automatische Veröffentlichung. Man würde es projektbezogen machen und als umgebungsgebundenes Geheimnis in den GitHub-Repository-Einstellungen speichern und es beispielsweise ${{ secrets.PYPI_API_TOKEN }} nennen. Siehe Erstellen und Verwenden von Geheimnissen. Obwohl es immer noch sicher ist, wird vertrauenswürdiges Veröffentlichen über API-Tokens jetzt als Best Practice auf unterstützten Plattformen (wie GitHub) empfohlen.
Die Docker-Datei sowie die zugehörigen Skripte und Dokumentationen in diesem Projekt werden unter der BSD-3-Klausel-Lizenz veröffentlicht.
