Release automatiche dei plugin

Le release automatiche compilano e pubblicano un plugin sandboxed quando invii un tag di versione o avvii manualmente un workflow di GitHub Actions. Il tuo account Atmosphere rimane proprietario del profilo del pacchetto e dei record di release. GitHub identifica il workflow approvato e il servizio di release verifica la build e scrive la release tramite una delega ristretta. Il repository non memorizza una credenziale dell’account Atmosphere.

Usa emdash-plugin publish per una release avviata dal tuo computer. Usa questa guida quando GitHub Actions deve compilare e pubblicare le release.

Prerequisiti

Prepara quanto segue prima di iniziare:

• Un repository GitHub pubblico contenente un plugin EmDash sandboxed.
• @emdash-cms/plugin-cli installato come dipendenza di sviluppo. I plugin creati con la CLI lo includono già.
• Un emdash-plugin.jsonc valido con slug, publisher, license, un autore e un contatto di sicurezza. Imposta repo sull’URL GitHub canonico, oppure conferma il remote GitHub rilevato durante la configurazione interattiva.
• Una versione in package.json, oppure in emdash-plugin.jsonc per un plugin solo di registro.
• L’account Atmosphere indicato da publisher.
• Un browser che supporta le passkey. L’approvazione della release richiede la verifica dell’utente.

Esegui il controllo del manifesto prima di configurare il workflow:

pnpm exec emdash-plugin validate

Configurare le release automatiche

Collegare un workflow Changesets

Il .github/workflows/emdash-release.yml generato accetta il JSON dei pacchetti pubblicati dell’Action Changesets tramite workflow_call. Aggiungi un output al job Changesets esistente, quindi chiama il workflow EmDash da un job dipendente. Sostituisci release e changesets quando il job o lo step esistente usa un altro ID.

Changesets Action v2 usa l’output published-packages. Aggiungi il seguente output di job e il chiamante a un workflow che usa 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 usa l’output dello step in camel-case publishedPackages. Usa questa espressione per un workflow che usa 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

Lascia Changesets responsabile della sua pull request di versione e della pubblicazione del pacchetto. Il chiamante EmDash viene eseguito solo quando Changesets segnala published: true. Per i pacchetti privati solo EmDash, imposta sia privatePackages.version sia privatePackages.tag su true in .changeset/config.json. Aggiungi applicazioni private non correlate e fixture di test a ignore.

Aggiungere un altro pacchetto

Prepara il profilo del pacchetto dalla sua directory di origine. Vengono riutilizzati il workflow root esistente e la connessione del repository:

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

Con Changesets, aggiungi il pacchetto a un changeset e unisci la sua pull request di versione. Con il trigger del tag di pacchetto, aggiorna la versione del pacchetto e invia il suo tag:

git tag comments@1.0.0
git push origin comments@1.0.0

Il workflow risolve comments in un emdash-plugin.jsonc, controlla la versione selezionata e verifica che il profilo firmato nomini il repository connesso prima di accettare i caricamenti degli artefatti. ID di pacchetto duplicati e discrepanze di versione falliscono prima dell’attestazione.

Cosa verifica il servizio di release

Il servizio completa questi controlli prima di scrivere una release:

1. Il token OpenID Connect (OIDC) di GitHub nomina un repository, proprietario, workflow, ref, ambiente, commit, esecuzione e runner ospitato da GitHub autorizzati.
2. Il profilo del pacchetto esiste, è firmato dal publisher, contiene impostazioni di delegated-release e nomina lo stesso repository GitHub canonico.
3. Il pacchetto e la versione richiesti corrispondono al bundle del plugin compilato.
4. Il checksum del pacchetto corrisponde ai byte caricati.
5. La provenance di GitHub copre lo stesso bundle, repository, workflow, commit ed esecuzione.
6. L’accesso dichiarato del record di release corrisponde al manifesto del bundle.
7. Il record di versione non esiste ancora.
8. Qualsiasi approvazione passkey richiesta copre l’esatto risultato di verifica e la revisione corrente del profilo.

L’Action richiede un token OIDC di GitHub fresco per ogni chiamata al servizio. I file di bundle e provenance entrano nello storage transitorio privato solo dopo che il workflow è autorizzato. Il servizio carica i byte verificati di pacchetto e immagine sul personal data server (PDS) del publisher, crea lì il record di release ed espone la provenance verificata tramite un URL immutabile indirizzato per checksum.

Confini di autorità

Ogni credenziale ha un compito:

Il servizio memorizza lo stato del publisher e dell’approvatore separatamente. Accedere per visualizzare le tue release non concede accesso da operatore, e un’identità di operatore non può approvare una release come publisher.

Comportamento dell’Action

Il workflow generato usa l’Action da apps/release-action. L’Action accetta un bundle compilato più provenance Sigstore grezza, oppure un release-file di compatibilità contenente fonti di artefatti HTTPS legate al checksum. Non combinare release-file con input di bundle o provenance.

Il workflow generato standard fornisce questi input. Sono mostrati qui così puoi rivedere il file generato senza dover inferire cosa autorizza ciascun valore:

L’Action restituisce questi output:

Consulta il riferimento dell’Action per input opzionali, workflow con fonti URL personalizzate, controlli di polling e il comportamento esatto degli output.

Risoluzione dei problemi

PACKAGE_PROFILE_REQUIRED

Il profilo del pacchetto manca, è privo di impostazioni di delegated-release, usa un URL di repository non canonico oppure nomina un repository diverso dal workflow di GitHub.

Esegui la configurazione del profilo localmente con l’account del publisher, quindi riavvia il workflow:

pnpm exec emdash-plugin profile setup

Questo controllo viene eseguito prima che il servizio accetti i caricamenti di bundle o provenance.

Repository pubblico richiesto

GitHub usa una root di fiducia Sigstore privata per i repository privati e interni. Il verificatore delle release attualmente si fida solo della provenance pubblica di GitHub. Sposta il workflow di release in un repository pubblico oppure pubblica localmente con emdash-plugin publish.

WORKLOAD_NOT_ALLOWED

Il repository, il proprietario, il file di workflow, il ref o l’ambiente di GitHub non corrisponde alla policy del workflow approvata. Apri la dashboard delle release e approva una nuova connessione del workflow con l’ambito previsto.

PROFILE_FETCH_FAILED

Il servizio non ha potuto verificare il profilo dal PDS del publisher. Riprova quando il provider dell’account è disponibile. Esegui emdash-plugin profile setup se il profilo è stato rimosso o modificato.

POLL_TIMEOUT

L’Action ha raggiunto timeout-minutes prima che fossero completate l’approvazione del workflow, l’approvazione della release o la pubblicazione. Controlla lo stato dell’intent nella dashboard delle release prima di rieseguire. Una riesecuzione della stessa esecuzione di GitHub Actions riusa la sua chiave di idempotenza.

Revocare la pubblicazione automatica

Seleziona Turn off automated publishing nella dashboard delle release. La revoca cancella la delega di release trattenuta. I profili di pacchetto esistenti, le release, le etichette di moderazione, i plugin installati e l’accesso alla dashboard non cambiano.

Ricollega la pubblicazione e approva di nuovo il workflow prima della prossima release automatica.

Documentazione correlata

• Bundling and publishing tratta la pubblicazione locale e la validazione dei bundle.
• The plugin manifest definisce i metadati del pacchetto e l’accesso dichiarato.
• Capabilities and security spiega i permessi esaminati durante l’approvazione della release e l’installazione.
• The plugin registry spiega discovery, moderazione e verifica dell’installazione.