Publications automatisées de plugins

Les publications automatisées construisent et publient un plugin sandboxed lorsque vous poussez une balise de version ou démarrez manuellement un workflow GitHub Actions. Votre compte Atmosphere reste propriétaire du profil de paquet et des enregistrements de release. GitHub identifie le workflow approuvé, et le service de release vérifie la compilation et écrit la release via une délégation étroite. Le dépôt ne stocke pas d’identifiant de compte Atmosphere.

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

Prérequis

Préparez les éléments suivants avant de commencer :

Un dépôt GitHub public contenant un plugin EmDash sandboxed.
@emdash-cms/plugin-cli installé en dépendance de développement. Les plugins créés avec la CLI l’incluent déjà.
Un emdash-plugin.jsonc valide avec slug, publisher, license, un auteur et un contact de sécurité. Définissez repo sur l’URL GitHub canonique, ou confirmez le remote GitHub détecté pendant la configuration interactive.
Une version dans package.json, ou dans emdash-plugin.jsonc pour un plugin uniquement au registre.
Le compte Atmosphere nommé par publisher.
Un navigateur qui prend en charge les passkeys. L’approbation de release exige une vérification utilisateur.

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

pnpm exec emdash-plugin validate

Configurer les publications automatisées

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

Dans un monorepo, exécutez la commande dans le paquet du plugin ou passez --dir <plugin-directory>. Si le manifeste ne contient pas repo, la configuration détecte le remote GitHub origin et préremplit l’invite du dépôt.

La configuration demande quand une release nécessite une approbation :
- When plugin permissions increase est la valeur par défaut. Une release attend une approbation lorsque son accès déclaré s’élargit par rapport à la dernière release.
- For every release exige une approbation pour chaque version.
La configuration demande aussi si les releases exigent une provenance vérifiable. Require provenance est la valeur par défaut pour les publications automatisées. Choisissez Allow releases without provenance uniquement lorsque le même profil doit aussi accepter des releases publiées directement depuis un environnement local de confiance.

Le compte Atmosphere connecté devient l’approbateur initial. Le profil lie le paquet à l’URL canonique du dépôt GitHub et enregistre la politique de provenance sélectionnée.

Exécutez uniquement l’étape du profil lorsqu’un fichier de workflow existe déjà :
```
pnpm exec emdash-plugin profile setup
```
Après la publication du profil de paquet, cette commande affiche les commandes de release manuelle et GitHub Actions.

Dans un terminal non interactif, passez --yes pour accepter les politiques par défaut. Passez --repository <https-url> lorsque ni le manifeste ni le remote Git ne fournissent le dépôt, --provenance optional pour autoriser les releases sans provenance, et --confirmation always pour exiger une approbation pour chaque release.
Examinez et validez 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.

Si le dépôt contient .changeset/config.json, la configuration interactive propose Follow Changesets releases. Lorsque Changesets publie un paquet contenant emdash-plugin.jsonc, le workflow EmDash réutilisable publie la même version. Connectez-le au workflow Changesets existant comme décrit ci-dessous. Sinon, le workflow généré s’exécute pour les balises de paquet correspondant à <slug>@<version>. Les deux variantes prennent en charge les exécutions manuelles et peuvent être sélectionnées explicitement avec --trigger changesets|tags|manual.

Le workflow accorde à chaque job uniquement les permissions contents, id-token et attestations requises ; épingle les Actions tierces sur des identifiants de commit complets ; exécute la version exacte de la CLI du plugin qui a généré le fichier ; résout chaque paquet depuis son manifeste ; 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.

Le workflow se trouve à la racine du dépôt et est partagé par chaque paquet de plugin de ce dépôt. Exécuter release setup depuis un paquet imbriqué écrit toujours .github/workflows/emdash-release.yml à la racine.
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’autorisation conservée peut créer des enregistrements de release de paquet et téléverser des blobs de paquet ou d’image de listing. Elle ne peut pas créer ni modifier des profils de paquet, mettre à jour ou supprimer des releases, ni écrire dans une autre collection.
Démarrez le workflow de release.

Avec Changesets, fusionnez la pull request de version et laissez son job de publication se terminer. L’Action Changesets passe les paquets qu’elle a publiés au workflow EmDash réutilisable. Les paquets npm ordinaires sont ignorés ; les paquets contenant emdash-plugin.jsonc publient la même version sur EmDash.

Avec le déclencheur de balise de paquet, mettez à jour la version du paquet avant de créer la balise de version. Les commandes suivantes démarrent une release 1.2.3 :
```
git tag gallery@1.2.3
git push origin gallery@1.2.3
```
Vous pouvez aussi sélectionner Run workflow sur la page GitHub Actions du dépôt.
Approuvez chaque portée de ref du dépôt lors de sa première exécution.

Le service vérifie que le profil de paquet initiateur nomme le dépôt GitHub avant de créer une demande de connexion. L’Action écrit un lien dans le résumé du job GitHub et attend. Ouvrez le lien et confirmez le dépôt, le fichier de workflow, la branche ou la balise, et l’environnement.

Pour une exécution déclenchée par balise, choisissez All package version tags ou Only this tag. Une exécution manuelle demande une approbation la première fois que sa branche est utilisée. Confirmer une autre portée de balise ou de branche l’ajoute à la connexion du dépôt sans supprimer les portées existantes. Le service stocke les ID du dépôt et du propriétaire GitHub ainsi que les refs et environnements approuvés. Les paquets ultérieurs réutilisent ces portées uniquement lorsque leurs profils signés nomment le même dépôt.

Les approbations de paquet créées par des workflows générés plus anciens restent limitées à leurs paquets d’origine. Le premier paquet ou ref non correspondant demande une connexion de dépôt ; le service n’élargit pas automatiquement une approbation de paquet existante.
Approuvez la release lorsque c’est requis.

Une release qui élargit les permissions du plugin, ou un profil configuré pour une confirmation à chaque release, passe en Awaiting approval. Ouvrez l’URL d’approbation depuis la sortie de l’Action ou le tableau de bord des releases. Enregistrez une passkey si le compte approbateur n’en a pas déjà une, examinez le changement de permission, et approuvez ou rejetez la release.

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

Connecter un workflow Changesets

Le .github/workflows/emdash-release.yml généré accepte le JSON des paquets publiés de l’Action Changesets via workflow_call. Ajoutez une sortie au job Changesets existant, puis appelez le workflow EmDash depuis un job dépendant. Remplacez release et changesets lorsque le job ou l’étape existant utilise un autre ID.

Changesets Action v2 utilise la sortie published-packages. Ajoutez la sortie de job et l’appelant suivants à un workflow utilisant Changesets CLI v3 :

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 utilise la sortie d’étape en camel-case publishedPackages. Utilisez cette expression pour un workflow utilisant 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

Laissez Changesets responsable de sa pull request de version et de la publication du paquet. L’appelant EmDash s’exécute uniquement lorsque Changesets signale published: true. Pour les paquets privés uniquement EmDash, définissez privatePackages.version et privatePackages.tag sur true dans .changeset/config.json. Ajoutez les applications privées non liées et les fixtures de test à ignore.

Ajouter un autre paquet

Préparez le profil de paquet depuis son répertoire source. Le workflow racine existant et la connexion du dépôt sont réutilisés :

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

Avec Changesets, ajoutez le paquet à un changeset et fusionnez sa pull request de version. Avec le déclencheur de balise de paquet, mettez à jour la version du paquet et poussez sa balise :

git tag comments@1.0.0
git push origin comments@1.0.0

Le workflow résout comments vers un emdash-plugin.jsonc, vérifie la version sélectionnée et confirme que le profil signé nomme le dépôt connecté avant d’accepter les téléversements d’artefacts. Les ID de paquet en double et les écarts de version échouent avant l’attestation.

Ce que le service de release vérifie

Le service effectue ces contrôles avant d’écrire une release :

Le jeton OpenID Connect (OIDC) GitHub nomme un dépôt, propriétaire, workflow, ref, environnement, commit, exécution et runner hébergé par GitHub autorisés.
Le profil de paquet existe, est signé par l’éditeur, contient des paramètres de delegated-release et nomme le même dépôt GitHub canonique.
Le paquet et la version demandés correspondent au bundle de plugin construit.
La somme de contrôle du paquet correspond aux octets téléversé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 jeton OIDC GitHub frais pour chaque appel au service. Les fichiers de bundle et de provenance n’entrent dans un stockage transitoire privé qu’après l’autorisation du workflow. Le service téléverse les octets de paquet et d’image vérifiés vers le serveur de données personnelles (PDS) de l’éditeur, y crée l’enregistrement de release 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 :

Credential	Used by	Authority
Local CLI OAuth session	`emdash-plugin profile setup`	Create or update the publisher-owned package profile after local confirmation.
GitHub OIDC token	Release Action	Identify one GitHub workflow run to the service. It grants no AT Protocol write access.
Release-service delegation	Release service	Create package release records and upload the required blobs.
Publisher application session	Release dashboard	Authorise workflow connections and revoke delegated publishing.
Approver session and passkey	Approval page	Approve or reject one checksum-bound release verification.
Cloudflare Access identity	Service operator console	Operate the hosted service. It does not represent a publisher or approver.

Le service stocke l’état de l’éditeur et de l’approbateur séparément. Se connecter pour voir vos releases n’accorde pas d’accès opérateur, et une identité opérateur ne peut pas approuver une release en tant qu’éditeur.

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 à une somme de contrôle. Ne combinez pas release-file avec des entrées de bundle ou de provenance.

Le workflow généré standard fournit ces entrées. Elles sont présentées ici pour que vous puissiez examiner le fichier généré sans devoir déduire ce que chaque valeur autorise :

Input	Value
`service-url`	Release-service HTTPS origin.
`publisher-did`	DID that owns the package profile and releases.
`bundle-file`	The single tarball produced by `emdash-plugin release prepare`.
`provenance-file`	Raw `bundle-path` output from `actions/attest-build-provenance`.

L’Action renvoie ces sorties :

Output	Meaning
`connection-url`	Browser URL for first-run workflow approval.
`intent-id`	Release intent identifier.
`state`	Published, terminal, or `awaiting_approval` state.
`approval-url`	Browser URL when passkey approval is required.
`release-uri`	Published release AT URI.
`release-cid`	Published release record CID.
`reason-code`	Stable reason for a terminal intent.

Consultez la référence de l’Action pour les entrées optionnelles, les workflows à sources URL personnalisées, les contrôles d’interrogation et le comportement exact des sorties.

Dépannage

`PACKAGE_PROFILE_REQUIRED`

Le profil de paquet est manquant, n’a pas de paramètres de delegated-release, 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 de l’éditeur, puis redémarrez le workflow :

pnpm exec emdash-plugin profile setup

Ce contrôle s’exécute avant que le service n’accepte les téléversements de bundle ou de 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.

`WORKLOAD_NOT_ALLOWED`

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

`PROFILE_FETCH_FAILED`

Le service n’a pas pu vérifier le profil depuis le PDS de l’éditeur. Réessayez lorsque 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 de la release ou la publication ne soit terminée. Vérifiez l’état de l’intent dans le tableau de bord des releases avant de relancer. Une relance 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 des releases. La révocation efface la délégation de release conservée. Les profils de paquet existants, les releases, les libellés de modération, les plugins installés et la connexion au tableau de bord ne changent pas.

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

Documentation associée

Bundling and publishing couvre la publication locale et la validation des bundles.
The plugin manifest définit les métadonnées du paquet et l’accès déclaré.
Capabilities and security explique les permissions examiné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 de l’installation.