Automatisierte Plugin-Releases

Automatisierte Releases bauen und veröffentlichen ein sandboxed Plugin, wenn Sie einen Versions-Tag pushen oder einen GitHub-Actions-Workflow manuell starten. Ihr Atmosphere-Konto bleibt Eigentümer des Paketprofils und der Release-Datensätze. GitHub identifiziert den genehmigten Workflow, und der Release-Dienst prüft den Build und schreibt den Release über eine enge Delegation. Das Repository speichert keine Atmosphere-Kontodaten.

Verwenden Sie emdash-plugin publish für einen Release, der von Ihrem Computer gestartet wird. Verwenden Sie diesen Leitfaden, wenn GitHub Actions Releases bauen und veröffentlichen soll.

Voraussetzungen

Bereiten Sie Folgendes vor dem Start vor:

• Ein öffentliches GitHub-Repository mit einem sandboxed EmDash-Plugin.
• @emdash-cms/plugin-cli als Entwicklungsabhängigkeit installiert. Mit der CLI erstellte Plugins enthalten es bereits.
• Eine gültige emdash-plugin.jsonc mit slug, publisher, license, einem Autor und einem Sicherheitskontakt. Setzen Sie repo auf die kanonische GitHub-URL, oder bestätigen Sie die erkannte GitHub-Remote während der interaktiven Einrichtung.
• Eine Version in package.json oder in emdash-plugin.jsonc für ein nur im Registry vorhandenes Plugin.
• Das durch publisher benannte Atmosphere-Konto.
• Einen Browser, der Passkeys unterstützt. Die Release-Freigabe erfordert Benutzerverifizierung.

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

pnpm exec emdash-plugin validate

Automatisierte Releases einrichten

Einen Changesets-Workflow verbinden

Die generierte .github/workflows/emdash-release.yml akzeptiert das von der Changesets-Action veröffentlichte Paket-JSON über workflow_call. Fügen Sie dem vorhandenen Changesets-Job eine Ausgabe hinzu und rufen Sie den EmDash-Workflow dann aus einem abhängigen Job auf. Ersetzen Sie release und changesets, wenn der vorhandene Job oder Schritt eine andere ID verwendet.

Changesets Action v2 verwendet die Ausgabe published-packages. Fügen Sie die folgende Job-Ausgabe und den Caller zu einem Workflow hinzu, der Changesets CLI v3 verwendet:

jobs:
  release:
    # Keep the existing runner, permissions, and steps.
    outputs:
      published: ${{ steps.changesets.outputs.published }}
      published-packages: ${{ steps.changesets.outputs['published-packages'] }}

  publish-emdash-plugins:
    needs: release
    if: needs.release.outputs.published == 'true'
    uses: ./.github/workflows/emdash-release.yml
    with:
      published-packages: ${{ needs.release.outputs['published-packages'] }}
    permissions:
      contents: read
      id-token: write
      attestations: write

Changesets Action v1 verwendet die camel-case-Ausgabe publishedPackages des Schritts. Verwenden Sie diesen Ausdruck für einen Workflow mit Changesets CLI v2:

jobs:
  release:
    # Keep the existing runner, permissions, and steps.
    outputs:
      published: ${{ steps.changesets.outputs.published }}
      published-packages: ${{ steps.changesets.outputs.publishedPackages }}

  publish-emdash-plugins:
    needs: release
    if: needs.release.outputs.published == 'true'
    uses: ./.github/workflows/emdash-release.yml
    with:
      published-packages: ${{ needs.release.outputs['published-packages'] }}
    permissions:
      contents: read
      id-token: write
      attestations: write

Lassen Sie Changesets für seinen Versions-Pull-Request und die Paketveröffentlichung verantwortlich. Der EmDash-Caller läuft nur, wenn Changesets published: true meldet. Für private nur-EmDash-Pakete setzen Sie sowohl privatePackages.version als auch privatePackages.tag in .changeset/config.json auf true. Fügen Sie unrelated private Anwendungen und Test-Fixtures zu ignore hinzu.

Ein weiteres Paket hinzufügen

Bereiten Sie das Paketprofil aus seinem Quellverzeichnis vor. Der vorhandene Root-Workflow und die Repository-Verbindung werden wiederverwendet:

pnpm exec emdash-plugin profile setup --dir packages/comments

Mit Changesets fügen Sie das Paket einem Changeset hinzu und mergen Sie seinen Versions-Pull-Request. Mit dem Paket-Tag-Trigger aktualisieren Sie die Paketversion und pushen Sie seinen Tag:

git tag comments@1.0.0
git push origin comments@1.0.0

Der Workflow löst comments zu einer emdash-plugin.jsonc auf, prüft die gewählte Version und verifiziert, dass das signierte Profil das verbundene Repository benennt, bevor Artefakt-Uploads akzeptiert werden. Doppelte Paket-IDs und Versionsabweichungen scheitern vor der Attestierung.

Was der Release-Dienst prüft

Der Dienst schließt diese Prüfungen ab, bevor er einen Release schreibt:

1. Das GitHub-OpenID-Connect-(OIDC)-Token benennt ein autorisiertes Repository, einen Eigentümer, Workflow, Ref, Umgebung, Commit, Run und einen von GitHub gehosteten Runner.
2. Das Paketprofil existiert, ist vom Publisher signiert, enthält Delegated-Release-Einstellungen und benennt dasselbe kanonische GitHub-Repository.
3. Das angeforderte Paket und die Version stimmen mit dem gebauten Plugin-Bundle überein.
4. Die Paket-Prüfsumme stimmt mit den hochgeladenen Bytes überein.
5. Die GitHub-Provenance deckt dasselbe Bundle, Repository, denselben Workflow, Commit und Run ab.
6. Der deklarierte Zugriff des Release-Datensatzes stimmt mit dem Bundle-Manifest überein.
7. Der Versionsdatensatz existiert noch nicht.
8. Jede erforderliche Passkey-Freigabe deckt das genaue Prüfergebnis und die aktuelle Profilrevision ab.

Die Action fordert für jeden Dienstaufruf ein frisches GitHub-OIDC-Token an. Bundle- und Provenance-Dateien gelangen erst nach Autorisierung des Workflows in privaten transienten Speicher. Der Dienst lädt geprüfte Paket- und Bild-Bytes auf den Personal Data Server (PDS) des Publishers hoch, erstellt dort den Release-Datensatz und stellt die geprüfte Provenance über eine unveränderliche, prüfsummenadressierte URL bereit.

Autoritätsgrenzen

Jede Anmeldedatenart hat eine Aufgabe:

Der Dienst speichert Publisher- und Genehmiger-Zustand getrennt. Die Anmeldung zum Anzeigen Ihrer Releases gewährt keinen Operatorzugriff, und eine Operatoridentität kann keinen Release 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-Provenance oder eine Kompatibilitäts-release-file mit prüfsummengebundenen HTTPS-Artefaktquellen. Kombinieren Sie release-file nicht mit Bundle- oder Provenance-Eingaben.

Der standardmäßig generierte Workflow liefert diese Eingaben. Sie werden hier gezeigt, damit Sie die generierte Datei prüfen können, ohne ableiten zu müssen, was jeder Wert autorisiert:

Die Action liefert diese Ausgaben:

Siehe die Action-Referenz für optionale Eingaben, benutzerdefinierte URL-Quellen-Workflows, Polling-Steuerung und genaues Ausgabe-Verhalten.

Fehlerbehebung

PACKAGE_PROFILE_REQUIRED

Das Paketprofil fehlt, enthält keine Delegated-Release-Einstellungen, verwendet eine nicht kanonische Repository-URL oder benennt ein anderes Repository als der GitHub-Workflow.

Führen Sie die Profileinrichtung lokal mit dem Publisher-Konto aus und starten Sie den Workflow erneut:

pnpm exec emdash-plugin profile setup

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

Öffentliches Repository erforderlich

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

WORKLOAD_NOT_ALLOWED

Das GitHub-Repository, der Eigentümer, die Workflow-Datei, der Ref oder die Umgebung 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 Dienst konnte das Profil vom PDS des Publishers nicht verifizieren. Versuchen Sie es erneut, nachdem der Kontenanbieter 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 Workflow-Freigabe, Release-Freigabe oder Veröffentlichung abgeschlossen waren. Prüfen Sie im Release-Dashboard den Intent-Zustand, bevor Sie erneut ausführen. Ein erneuter Lauf desselben GitHub-Actions-Runs verwendet seinen Idempotenzschlüssel erneut.

Automatisierte Veröffentlichung widerrufen

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

Verbinden Sie die Veröffentlichung erneut und genehmigen Sie den Workflow erneut vor dem nächsten automatisierten Release.

Verwandte Dokumentation

• Bundling and publishing behandelt lokales Veröffentlichen und Bundle-Validierung.
• The plugin manifest definiert Paketmetadaten und deklarierten Zugriff.
• Capabilities and security erklärt die bei Release-Freigabe und Installation geprüften Berechtigungen.
• The plugin registry erklärt Discovery, Moderation und Installationsverifizierung.