Automatisierte Plugin-Releases

Automatisierte Releases bauen und veröffentlichen ein Sandboxed Plugin, wenn Sie ein Version-Tag pushen oder einen GitHub Actions Workflow manuell starten. Ihr Atmosphere-Account besitzt das Paketprofil und die Release-Einträge. GitHub identifiziert den genehmigten Workflow, und der Release-Service verifiziert und veröffentlicht das Ergebnis, ohne eine Account-Anmeldeinformation im Repository zu speichern.

Verwenden Sie emdash-plugin publish für ein Release von Ihrem Computer. Verwenden Sie diese Anleitung, wenn GitHub Actions Releases bauen und veröffentlichen soll.

Voraussetzungen

Bereiten Sie Folgendes vor:

Ein öffentliches GitHub-Repository mit einem Sandboxed EmDash Plugin.
Eine gültige emdash-plugin.jsonc mit slug, publisher, license, einem Autor und einem Sicherheitskontakt. Setzen Sie repo auf die kanonische GitHub-URL oder geben Sie sie während des interaktiven Setups ein.
Eine Version in package.json oder in emdash-plugin.jsonc für ein Nur-Registry-Plugin.
Den von publisher genannten Atmosphere-Account.
Berechtigung, ein GitHub Actions Secret zum Repository hinzuzufügen.
Einen Browser, der Passkeys unterstützt. Release-Genehmigung erfordert Benutzerverifizierung.

Führen Sie die Manifest-Prüfung aus, bevor Sie den Workflow konfigurieren:

pnpm exec emdash-plugin validate

Automatisierte Releases einrichten

Melden Sie sich im Plugin-CLI mit dem Atmosphere-Account an, der das Paket besitzt.
```
pnpm exec emdash-plugin login alice.example.com
```
Die CLI speichert diese lokale Publishing-Session außerhalb des Projekts. GitHub Actions erhält sie nie.
Bereiten Sie das Paketprofil vor und generieren Sie den Workflow.
```
pnpm exec emdash-plugin release setup
```
Der Befehl liest die Paket-Metadaten aus emdash-plugin.jsonc. Wenn das Paketprofil fehlt, bietet er an, es zu erstellen. Wenn das Profil ohne delegierte Release-Einstellungen existiert, bietet er an, sie hinzuzufügen und die bestehenden Paket-Metadaten beizubehalten.

Setup fragt, wann ein Release eine Genehmigung benötigt:
- Bei Erweiterung der Plugin-Berechtigungen ist der Standard. Ein Release wartet auf Genehmigung, wenn sein deklarierter Zugriff relativ zum letzten Release erweitert wird.
- Für jedes Release erfordert eine Genehmigung für jede Version.
Der angemeldete Atmosphere-Account wird zum initialen Genehmiger. Das Profil bindet das Paket auch an die kanonische GitHub-Repository-URL und erfordert verifizierbare Provenienz.

Führen Sie nur den Profil-Schritt aus, wenn bereits eine Workflow-Datei existiert:
```
pnpm exec emdash-plugin profile setup
```
In einem nicht-interaktiven Terminal übergeben Sie --yes, um die Standard-Genehmigungsrichtlinie zu akzeptieren. Übergeben Sie --repository <https-url>, wenn das Manifest kein repo enthält, und --confirmation always, um eine Genehmigung für jedes Release zu erfordern.
Überprüfen und committen Sie den generierten Workflow.

Der Befehl erstellt .github/workflows/emdash-release.yml. Er pusht die Datei nicht und ersetzt keinen bestehenden Workflow, es sei denn, Sie übergeben --force.

Der generierte Workflow läuft für Version-Tags, die v* entsprechen, und durch workflow_dispatch. Er gewährt contents: read, id-token: write und attestations: write; pinnt Third-Party Actions auf vollständige Commit-Identifikatoren; baut ein Plugin-Bundle; erstellt GitHub Build-Provenienz für genau diese Bytes; und übergibt beide Dateien an die EmDash Release Action.
Öffnen Sie das Release-Service Dashboard und melden Sie sich mit demselben Atmosphere-Account an.

Wählen Sie Authorize publishing. Ihr Account-Provider zeigt die exakte delegierte Berechtigung. Die beibehaltene Gewährung kann Paket-Release-Einträge erstellen und Paket- oder Listing-Image-Blobs hochladen. Sie kann keine Paketprofile erstellen oder bearbeiten, Releases aktualisieren oder löschen oder in eine andere Collection schreiben.
Erstellen Sie eine Workflow-Einladung.

Geben Sie die Plugin-ID aus emdash-plugin.jsonc ein und wählen Sie Create invitation. Fügen Sie den Einmalwert als Actions Secret namens EMDASH_CONNECTION_INVITATION zum GitHub-Repository hinzu.

Die Einladung ist 30 Minuten gültig und kann nur das benannte Plugin verbinden. Erstellen Sie eine neue Einladung, wenn sie abläuft, bevor der Workflow sie verwendet.
Starten Sie den Release-Workflow.

Aktualisieren Sie die Paketversion, bevor Sie das Version-Tag erstellen. Die folgenden Befehle starten ein 1.2.3-Release:
```
git tag v1.2.3
git push origin v1.2.3
```
Sie können auch Run workflow auf der GitHub Actions Seite des Repositorys auswählen.
Genehmigen Sie die Workflow-Verbindung beim ersten Lauf.

Die Action schreibt einen Link in die GitHub Job Summary und wartet. Öffnen Sie den Link und bestätigen Sie Plugin, Repository, Workflow-Datei, Branch oder Tag und Umgebung.

Für einen Tag-ausgelösten Lauf wählen Sie All version tags oder Only this tag. Eine Branch-ausgelöste Anfrage deckt nur diesen Branch ab. Der Service speichert die GitHub Repository- und Owner-IDs sowie den ausgewählten Ref und Environment-Scope. Spätere Läufe müssen dieser Richtlinie entsprechen.
Genehmigen Sie das Release, wenn erforderlich.

Ein Release, das Plugin-Berechtigungen erweitert, oder ein Profil, das für jede Release-Bestätigung konfiguriert ist, wechselt in Awaiting approval. Öffnen Sie die Genehmigungs-URL aus der Action-Ausgabe oder dem Release-Dashboard. Registrieren Sie einen Passkey, wenn der genehmigende Account noch keinen hat, überprüfen Sie die Berechtigungsänderung und genehmigen oder lehnen Sie das Release ab.

Die Standard-Action-Einstellung kehrt erfolgreich zurück, wenn das Release Awaiting approval erreicht. Der Service-Workflow wartet weiter auf die Browser-Entscheidung und veröffentlicht nach Genehmigung.

Was der Release-Service verifiziert

Der Service führt diese Prüfungen durch, bevor er ein Release schreibt:

Das GitHub OpenID Connect (OIDC) Token nennt ein autorisiertes Repository, Owner, Workflow, Ref, Environment, Commit, Run und GitHub-hosted Runner.
Das Paketprofil existiert, ist vom Publisher signiert, enthält delegierte Release-Einstellungen und nennt dasselbe kanonische GitHub-Repository.
Das angeforderte Paket und die Version stimmen mit dem gebauten Plugin-Bundle überein.
Die Paketprüfsumme stimmt mit den hochgeladenen Bytes überein.
Die GitHub-Provenienz deckt dasselbe Bundle, Repository, Workflow, Commit und Run ab.
Der deklarierte Zugriff des Release-Eintrags stimmt mit dem Bundle-Manifest überein.
Der Versions-Eintrag existiert noch nicht.
Jede erforderliche Passkey-Genehmigung deckt das exakte Verifikationsergebnis und die aktuelle Profilrevision ab.

Die Action fordert für jeden Service-Aufruf ein frisches GitHub OIDC Token an. Bundle- und Provenienz-Dateien gelangen nur nach Autorisierung des Workflows in den privaten temporären Speicher. Der Service lädt verifizierte Paket- und Image-Bytes auf den persönlichen Datenserver (PDS) des Publishers hoch, erstellt dort den Release-Eintrag und stellt die verifizierte Provenienz über eine unveränderliche prüfsummenadressierte URL bereit.

Autoritätsgrenzen

Jede Anmeldeinformation hat eine Aufgabe:

Anmeldeinformation	Verwendet von	Autorität
Lokale CLI OAuth-Session	`emdash-plugin profile setup`	Erstellen oder Aktualisieren des Publisher-eigenen Paketprofils nach lokaler Bestätigung.
GitHub OIDC Token	Release Action	Identifiziert einen GitHub Workflow-Lauf beim Service. Es gewährt keinen AT Protocol Schreibzugriff.
Release-Service Delegation	Release Service	Erstellt Paket-Release-Einträge und lädt die erforderlichen Blobs hoch.
Publisher Application Session	Release Dashboard	Autorisiert Workflow-Verbindungen und widerruft delegiertes Publishing.
Genehmiger-Session und Passkey	Genehmigungsseite	Genehmigt oder lehnt eine prüfsummengebundene Release-Verifikation ab.
Cloudflare Access Identity	Service-Betreiberkonsole	Betreibt den gehosteten Service. Er repräsentiert keinen Publisher oder Genehmiger.

Der Service speichert Publisher- und Genehmiger-Status separat. Das Anmelden zum Anzeigen Ihrer Releases gewährt keinen Betreiberzugriff, und eine Betreiber-Identität kann ein Release nicht als Publisher genehmigen.

Action-Verhalten

Der generierte Workflow verwendet die Action aus apps/release-action. Die Action akzeptiert entweder ein gebautes Bundle plus rohe Sigstore-Provenienz oder eine Kompatibilitäts-release-file mit prüfsummengebundenen HTTPS-Artefaktquellen. Kombinieren Sie release-file nicht mit Bundle- oder Provenienz-Eingaben.

Der standardmäßig generierte Workflow liefert diese Eingaben:

Eingabe	Wert
`service-url`	Release-Service HTTPS Origin.
`publisher-did`	DID, das Paketprofil und Releases besitzt.
`connection-invitation`	`EMDASH_CONNECTION_INVITATION` bei der ersten Verbindung.
`bundle-file`	Der einzelne Tarball, der von `emdash-plugin bundle` erzeugt wird.
`provenance-file`	Rohe `bundle-path` Ausgabe von `actions/attest-build-provenance`.

Die Action gibt diese Ausgaben zurück:

Ausgabe	Bedeutung
`connection-url`	Browser-URL für die Workflow-Genehmigung beim ersten Lauf.
`intent-id`	Release-Intent-Identifikator.
`state`	Published, Terminal oder `awaiting_approval` Status.
`approval-url`	Browser-URL wenn Passkey-Genehmigung erforderlich ist.
`release-uri`	Veröffentlichte Release AT URI.
`release-cid`	Veröffentlichte Release Record CID.
`reason-code`	Stabiler Grund für einen terminalen Intent.

Siehe die Action-Referenz für optionale Eingaben, benutzerdefinierte URL-Source-Workflows, Polling-Steuerungen und exaktes Ausgabeverhalten.

Fehlerbehebung

`PACKAGE_PROFILE_REQUIRED`

Das Paketprofil fehlt, hat keine delegierten Release-Einstellungen, verwendet eine nicht-kanonische Repository-URL oder nennt ein anderes Repository als den GitHub-Workflow.

Führen Sie das Profil-Setup lokal mit dem Publisher-Account aus und starten Sie dann den Workflow erneut:

pnpm exec emdash-plugin profile setup

Diese Prüfung läuft, bevor der Service Bundle- oder Provenienz-Uploads akzeptiert.

Öffentliches Repository erforderlich

GitHub verwendet einen privaten Sigstore Trust Root für private und interne Repositories. Der Release-Verifier vertraut derzeit nur öffentlicher GitHub-Provenienz. Verschieben Sie den Release-Workflow in ein öffentliches Repository oder veröffentlichen Sie lokal mit emdash-plugin publish.

Einladung abgelaufen oder ungültig

Erstellen Sie eine weitere Einladung im Release-Dashboard und ersetzen Sie EMDASH_CONNECTION_INVITATION. Starten Sie den Workflow innerhalb von 30 Minuten. Eine Einladung ist einmalig verwendbar und auf eine Plugin-ID beschränkt.

`WORKLOAD_NOT_ALLOWED`

Das GitHub-Repository, der Owner, die Workflow-Datei, der Ref oder das Environment stimmt nicht mit der genehmigten Workflow-Richtlinie überein. Öffnen Sie das Release-Dashboard und genehmigen Sie eine neue Workflow-Verbindung mit dem beabsichtigten Scope.

`PROFILE_FETCH_FAILED`

Der Service konnte das Profil vom PDS des Publishers nicht verifizieren. Versuchen Sie es erneut, wenn der Account-Provider verfügbar ist. Führen Sie emdash-plugin profile setup aus, wenn das Profil entfernt oder geändert wurde.

`POLL_TIMEOUT`

Die Action hat timeout-minutes erreicht, bevor die Workflow-Genehmigung, Release-Genehmigung oder Veröffentlichung abgeschlossen war. Überprüfen Sie den Intent-Status im Release-Dashboard, bevor Sie erneut starten. Ein Rerun desselben GitHub Actions Run verwendet seinen Idempotenzschlüssel wieder.

Automatisiertes Publishing widerrufen

Wählen Sie Turn off automated publishing im Release-Dashboard. Der Widerruf löscht die beibehaltene Release-Delegation. Bestehende Paketprofile, Releases, Moderationslabels, installierte Plugins und der Dashboard-Login ändern sich nicht.

Verbinden Sie das Publishing erneut und genehmigen Sie den Workflow vor dem nächsten automatisierten Release.