Releases automatisés de plugins | EmDash CMS Everything

Les releases automatisés construisent et publient un plugin sandboxé lorsque vous poussez un tag de version ou démarrez manuellement un workflow GitHub Actions. Votre compte Atmosphere possède le profil du package et les enregistrements de release. GitHub identifie le workflow approuvé, et le service de release vérifie et publie le résultat sans stocker d’identifiant de compte dans le dépôt.

Utilisez emdash-plugin publish pour un release démarré depuis votre ordinateur. Utilisez ce guide lorsque GitHub Actions doit construire et publier les releases.

Prérequis

Préparez les éléments suivants :

Un dépôt GitHub public contenant un plugin EmDash sandboxé.
Un emdash-plugin.jsonc valide avec slug, publisher, license, un auteur et un contact de sécurité. Définissez repo à l’URL GitHub canonique, ou saisissez-la lors de la configuration interactive.
Une version dans package.json, ou dans emdash-plugin.jsonc pour un plugin uniquement registre.
Le compte Atmosphere nommé par publisher.
La permission d’ajouter un secret GitHub Actions au dépôt.
Un navigateur supportant les passkeys. L’approbation de release nécessite une vérification utilisateur.

Exécutez la vérification du manifeste avant de configurer le workflow :

pnpm exec emdash-plugin validate

Configurer les releases automatisés

Connectez-vous au CLI du plugin avec le compte Atmosphere propriétaire du package.
```
pnpm exec emdash-plugin login alice.example.com
```
Le CLI stocke cette session de publication locale en dehors du projet. GitHub Actions ne la reçoit jamais.
Préparez le profil du package et générez le workflow.
```
pnpm exec emdash-plugin release setup
```
La commande lit les métadonnées du package depuis emdash-plugin.jsonc. Si le profil du package est absent, elle propose de le créer. Si le profil existe sans paramètres de release délégué, elle propose de les ajouter en préservant les métadonnées existantes.

La configuration demande quand un release nécessite une approbation :
- Lorsque les permissions du plugin augmentent est la valeur par défaut. Un release attend l’approbation lorsque son accès déclaré s’étend par rapport au dernier release.
- Pour chaque release nécessite une approbation pour chaque version.
Le compte Atmosphere connecté devient l’approbateur initial. Le profil lie également le package à l’URL canonique du dépôt GitHub et exige une provenance vérifiable.

Exécutez uniquement l’étape du profil lorsqu’un fichier workflow existe déjà :
```
pnpm exec emdash-plugin profile setup
```
Dans un terminal non interactif, passez --yes pour accepter la politique d’approbation par défaut. Passez --repository <https-url> lorsque le manifeste ne contient pas repo, et --confirmation always pour exiger une approbation pour chaque release.
Révisez et committez le workflow généré.

La commande crée .github/workflows/emdash-release.yml. Elle ne pousse pas le fichier et ne remplace pas un workflow existant sauf si vous passez --force.

Le workflow généré s’exécute pour les tags de version correspondant à v* et via workflow_dispatch. Il accorde contents: read, id-token: write et attestations: write ; fixe les Actions tierces à des identifiants de commit complets ; construit un bundle de plugin ; crée une provenance de build GitHub pour ces octets exacts ; et passe les deux fichiers à l’Action de release EmDash.
Ouvrez le tableau de bord du service de release et connectez-vous avec le même compte Atmosphere.

Sélectionnez Authorize publishing. Votre fournisseur de compte affiche la permission déléguée exacte. L’octroi retenu peut créer des enregistrements de release de package et télécharger des blobs de package ou d’image de listing. Il ne peut pas créer ou modifier des profils de package, mettre à jour ou supprimer des releases, ou écrire dans une autre collection.
Créez une invitation de workflow.

Entrez l’ID du plugin depuis emdash-plugin.jsonc, puis sélectionnez Create invitation. Ajoutez la valeur à usage unique au dépôt GitHub comme secret Actions nommé EMDASH_CONNECTION_INVITATION.

L’invitation est valable 30 minutes et ne peut connecter que le plugin nommé. Créez une nouvelle invitation si elle expire avant que le workflow ne la consomme.
Démarrez le workflow de release.

Mettez à jour la version du package avant de créer le tag de version. Les commandes suivantes démarrent un release 1.2.3 :
```
git tag v1.2.3
git push origin v1.2.3
```
Vous pouvez également sélectionner Run workflow sur la page GitHub Actions du dépôt.
Approuvez la connexion du workflow lors de sa première exécution.

L’Action écrit un lien dans le résumé du job GitHub et attend. Ouvrez le lien et confirmez le plugin, le dépôt, le fichier workflow, la branche ou le tag, et l’environnement.

Pour une exécution déclenchée par tag, choisissez All version tags ou Only this tag. Une requête déclenchée par branche ne couvre que cette branche. Le service stocke les IDs du dépôt et du propriétaire GitHub ainsi que le ref et le scope d’environnement sélectionnés. Les exécutions ultérieures doivent correspondre à cette politique.
Approuvez le release lorsque nécessaire.

Un release qui étend les permissions du plugin, ou un profil configuré pour confirmation à chaque release, entre en Awaiting approval. Ouvrez l’URL d’approbation depuis la sortie de l’Action ou le tableau de bord. Enregistrez un passkey si le compte approbateur n’en a pas encore, révisez le changement de permission et approuvez ou rejetez le release.

Le paramètre par défaut de l’Action retourne avec succès lorsque le release atteint Awaiting approval. Le workflow du service continue d’attendre la décision du navigateur et publie après approbation.

Ce que le service de release vérifie

Le service effectue ces vérifications avant d’écrire un release :

Le token GitHub OpenID Connect (OIDC) nomme un dépôt, propriétaire, workflow, ref, environnement, commit, exécution et runner hébergé GitHub autorisés.
Le profil du package existe, est signé par le publieur, contient des paramètres de release délégué et nomme le même dépôt GitHub canonique.
Le package et la version demandés correspondent au bundle de plugin construit.
La somme de contrôle du package correspond aux octets téléchargés.
La provenance GitHub couvre le même bundle, dépôt, workflow, commit et exécution.
L’accès déclaré de l’enregistrement de release correspond au manifeste du bundle.
L’enregistrement de version n’existe pas encore.
Toute approbation passkey requise couvre le résultat exact de vérification et la révision actuelle du profil.

L’Action demande un token OIDC GitHub frais pour chaque appel au service. Les fichiers de bundle et provenance entrent dans un stockage transitoire privé uniquement après autorisation du workflow. Le service télécharge les octets vérifiés du package et de l’image vers le serveur de données personnel (PDS) du publieur, crée l’enregistrement de release là-bas et expose la provenance vérifiée via une URL immuable adressée par somme de contrôle.

Limites d’autorité

Chaque identifiant a un rôle :

Identifiant	Utilisé par	Autorité
Session OAuth locale du CLI	`emdash-plugin profile setup`	Créer ou mettre à jour le profil du package après confirmation locale.
Token OIDC GitHub	Action de release	Identifier une exécution de workflow GitHub auprès du service. N’accorde aucun accès en écriture AT Protocol.
Délégation du service de release	Service de release	Créer des enregistrements de release et télécharger les blobs requis.
Session d’application du publieur	Tableau de bord	Autoriser les connexions de workflow et révoquer la publication déléguée.
Session et passkey de l’approbateur	Page d’approbation	Approuver ou rejeter une vérification de release liée par somme de contrôle.
Identité Cloudflare Access	Console opérateur	Opérer le service hébergé. Ne représente pas un publieur ou approbateur.

Le service stocke les états du publieur et de l’approbateur séparément. Se connecter pour voir vos releases n’accorde pas l’accès opérateur, et une identité opérateur ne peut pas approuver un release en tant que publieur.

Comportement de l’Action

Le workflow généré utilise l’Action de apps/release-action. L’Action accepte soit un bundle construit plus une provenance Sigstore brute, soit un release-file de compatibilité contenant des sources d’artefacts HTTPS liées par somme de contrôle. Ne combinez pas release-file avec des entrées de bundle ou provenance.

Le workflow standard généré fournit ces entrées :

Entrée	Valeur
`service-url`	Origine HTTPS du service de release.
`publisher-did`	DID propriétaire du profil et des releases.
`connection-invitation`	`EMDASH_CONNECTION_INVITATION` à la première connexion.
`bundle-file`	Le tarball unique produit par `emdash-plugin bundle`.
`provenance-file`	Sortie `bundle-path` brute de `actions/attest-build-provenance`.

L’Action retourne ces sorties :

Sortie	Signification
`connection-url`	URL navigateur pour l’approbation du workflow à la première exécution.
`intent-id`	Identifiant d’intention de release.
`state`	État Published, terminal ou `awaiting_approval`.
`approval-url`	URL navigateur quand l’approbation passkey est requise.
`release-uri`	URI AT du release publié.
`release-cid`	CID de l’enregistrement de release publié.
`reason-code`	Raison stable pour un intent terminal.

Voir la référence de l’Action pour les entrées optionnelles, les workflows de source URL personnalisés, les contrôles de polling et le comportement exact de sortie.

Dépannage

`PACKAGE_PROFILE_REQUIRED`

Le profil du package est absent, manque de paramètres de release délégué, utilise une URL de dépôt non canonique ou nomme un dépôt différent du workflow GitHub.

Exécutez la configuration du profil localement avec le compte publieur, puis redémarrez le workflow :

pnpm exec emdash-plugin profile setup

Cette vérification s’exécute avant que le service n’accepte les téléchargements de bundle ou provenance.

Dépôt public requis

GitHub utilise une racine de confiance Sigstore privée pour les dépôts privés et internes. Le vérificateur de release ne fait actuellement confiance qu’à la provenance GitHub publique. Déplacez le workflow de release vers un dépôt public ou publiez localement avec emdash-plugin publish.

Invitation expirée ou invalide

Créez une autre invitation dans le tableau de bord et remplacez EMDASH_CONNECTION_INVITATION. Démarrez le workflow dans les 30 minutes. Une invitation est à usage unique et limitée à un ID de plugin.

`WORKLOAD_NOT_ALLOWED`

Le dépôt GitHub, propriétaire, fichier workflow, ref ou environnement ne correspond pas à la politique de workflow approuvée. Ouvrez le tableau de bord et approuvez une nouvelle connexion de workflow avec le scope prévu.

`PROFILE_FETCH_FAILED`

Le service n’a pas pu vérifier le profil depuis le PDS du publieur. Réessayez quand le fournisseur de compte est disponible. Exécutez emdash-plugin profile setup si le profil a été supprimé ou modifié.

`POLL_TIMEOUT`

L’Action a atteint timeout-minutes avant que l’approbation du workflow, l’approbation du release ou la publication ne se termine. Vérifiez l’état de l’intent dans le tableau de bord avant de relancer. Une réexécution de la même exécution GitHub Actions réutilise sa clé d’idempotence.

Révoquer la publication automatisée

Sélectionnez Turn off automated publishing dans le tableau de bord. La révocation supprime la délégation de release retenue. Les profils de packages existants, releases, labels de modération, plugins installés et la connexion au tableau de bord ne changent pas.

Reconnectez la publication et approuvez le workflow à nouveau avant le prochain release automatisé.

Documentation connexe

Bundling and publishing couvre la publication locale et la validation des bundles.
The plugin manifest définit les métadonnées du package et l’accès déclaré.
Capabilities and security explique les permissions révisées lors de l’approbation de release et de l’installation.
The plugin registry explique la découverte, la modération et la vérification d’installation.