Rilasci automatizzati dei plugin | EmDash CMS Everything

I rilasci automatizzati compilano e pubblicano un plugin sandboxato quando si effettua il push di un tag di versione o si avvia manualmente un workflow di GitHub Actions. Il tuo account Atmosphere possiede il profilo del pacchetto e i record di rilascio. GitHub identifica il workflow approvato e il servizio di rilascio verifica e pubblica il risultato senza memorizzare credenziali dell’account nel repository.

Usa emdash-plugin publish per un rilascio avviato dal tuo computer. Usa questa guida quando GitHub Actions deve compilare e pubblicare i rilasci.

Prerequisiti

Prepara quanto segue prima di iniziare:

Un repository GitHub pubblico contenente un plugin EmDash sandboxato.
Un emdash-plugin.jsonc valido con slug, publisher, license, un autore e un contatto di sicurezza. Imposta repo all’URL GitHub canonico, oppure inseriscilo durante la configurazione interattiva.
Una versione in package.json, o in emdash-plugin.jsonc per un plugin solo registro.
L’account Atmosphere indicato da publisher.
Il permesso di aggiungere un secret GitHub Actions al repository.
Un browser che supporta le passkey. L’approvazione del rilascio richiede la verifica dell’utente.

Esegui il controllo del manifesto prima di configurare il workflow:

pnpm exec emdash-plugin validate

Configurare i rilasci automatizzati

Accedi al CLI del plugin con l’account Atmosphere proprietario del pacchetto.
```
pnpm exec emdash-plugin login alice.example.com
```
Il CLI memorizza questa sessione di pubblicazione locale al di fuori del progetto. GitHub Actions non la riceve mai.
Prepara il profilo del pacchetto e genera il workflow.
```
pnpm exec emdash-plugin release setup
```
Il comando legge i metadati del pacchetto da emdash-plugin.jsonc. Se il profilo del pacchetto è assente, propone di crearlo. Se il profilo esiste senza impostazioni di rilascio delegato, propone di aggiungerle preservando i metadati del pacchetto esistenti.

La configurazione chiede quando un rilascio necessita di approvazione:
- Quando i permessi del plugin aumentano è l’impostazione predefinita. Un rilascio attende l’approvazione quando il suo accesso dichiarato si espande rispetto all’ultimo rilascio.
- Per ogni rilascio richiede l’approvazione per ogni versione.
L’account Atmosphere connesso diventa l’approvatore iniziale. Il profilo associa inoltre il pacchetto all’URL canonico del repository GitHub e richiede una provenienza verificabile.

Esegui solo la fase del profilo quando un file workflow esiste già:
```
pnpm exec emdash-plugin profile setup
```
In un terminale non interattivo, passa --yes per accettare la politica di approvazione predefinita. Passa --repository <https-url> quando il manifesto non contiene repo, e --confirmation always per richiedere l’approvazione per ogni rilascio.
Rivedi e committa il workflow generato.

Il comando crea .github/workflows/emdash-release.yml. Non effettua il push del file e non sostituisce un workflow esistente a meno che non si passi --force.

Il workflow generato si esegue per tag di versione corrispondenti a v* e tramite workflow_dispatch. Concede contents: read, id-token: write e attestations: write; fissa le Actions di terze parti a identificatori di commit completi; compila un bundle del plugin; crea una provenienza di build GitHub per quei byte esatti; e passa entrambi i file all’Action di rilascio EmDash.
Apri la dashboard del servizio di rilascio e accedi con lo stesso account Atmosphere.

Seleziona Authorize publishing. Il tuo fornitore di account mostra il permesso delegato esatto. La concessione conservata può creare record di rilascio del pacchetto e caricare blob del pacchetto o dell’immagine del listing. Non può creare o modificare profili del pacchetto, aggiornare o eliminare rilasci, o scrivere in un’altra collezione.
Crea un invito per il workflow.

Inserisci l’ID del plugin da emdash-plugin.jsonc, quindi seleziona Create invitation. Aggiungi il valore monouso al repository GitHub come secret Actions denominato EMDASH_CONNECTION_INVITATION.

L’invito è valido per 30 minuti e può connettere solo il plugin indicato. Crea un nuovo invito se scade prima che il workflow lo consumi.
Avvia il workflow di rilascio.

Aggiorna la versione del pacchetto prima di creare il tag di versione. I seguenti comandi avviano un rilascio 1.2.3:
```
git tag v1.2.3
git push origin v1.2.3
```
Puoi anche selezionare Run workflow nella pagina GitHub Actions del repository.
Approva la connessione del workflow alla prima esecuzione.

L’Action scrive un link nel riepilogo del job GitHub e attende. Apri il link e conferma il plugin, il repository, il file workflow, il branch o tag e l’ambiente.

Per un’esecuzione attivata da tag, scegli All version tags o Only this tag. Una richiesta attivata da branch copre solo quel branch. Il servizio memorizza gli ID del repository e del proprietario GitHub nonché il ref e lo scope dell’ambiente selezionati. Le esecuzioni successive devono corrispondere a questa politica.
Approva il rilascio quando richiesto.

Un rilascio che espande i permessi del plugin, o un profilo configurato per la conferma ad ogni rilascio, entra in Awaiting approval. Apri l’URL di approvazione dall’output dell’Action o dalla dashboard dei rilasci. Registra una passkey se l’account approvatore non ne ha ancora una, rivedi la modifica dei permessi e approva o rifiuta il rilascio.

L’impostazione predefinita dell’Action ritorna con successo quando il rilascio raggiunge Awaiting approval. Il workflow del servizio continua ad attendere la decisione del browser e pubblica dopo l’approvazione.

Cosa verifica il servizio di rilascio

Il servizio completa questi controlli prima di scrivere un rilascio:

Il token GitHub OpenID Connect (OIDC) nomina un repository, proprietario, workflow, ref, ambiente, commit, esecuzione e runner ospitato GitHub autorizzati.
Il profilo del pacchetto esiste, è firmato dal pubblicatore, contiene impostazioni di rilascio delegato e nomina lo stesso repository GitHub canonico.
Il pacchetto e la versione richiesti corrispondono al bundle del plugin compilato.
Il checksum del pacchetto corrisponde ai byte caricati.
La provenienza GitHub copre lo stesso bundle, repository, workflow, commit ed esecuzione.
L’accesso dichiarato del record di rilascio corrisponde al manifesto del bundle.
Il record di versione non esiste ancora.
Qualsiasi approvazione passkey richiesta copre il risultato di verifica esatto e la revisione corrente del profilo.

L’Action richiede un token OIDC GitHub fresco per ogni chiamata al servizio. I file bundle e provenienza entrano in un archivio transitorio privato solo dopo l’autorizzazione del workflow. Il servizio carica i byte verificati del pacchetto e dell’immagine sul server dati personale (PDS) del pubblicatore, crea il record di rilascio lì ed espone la provenienza verificata attraverso un URL immutabile indirizzato tramite checksum.

Limiti di autorità

Ogni credenziale ha un ruolo:

Credenziale	Utilizzata da	Autorità
Sessione OAuth locale del CLI	`emdash-plugin profile setup`	Creare o aggiornare il profilo del pacchetto di proprietà del pubblicatore dopo conferma locale.
Token OIDC GitHub	Action di rilascio	Identificare un’esecuzione di workflow GitHub al servizio. Non concede accesso in scrittura AT Protocol.
Delegazione del servizio di rilascio	Servizio di rilascio	Creare record di rilascio del pacchetto e caricare i blob richiesti.
Sessione dell’applicazione del pubblicatore	Dashboard dei rilasci	Autorizzare le connessioni del workflow e revocare la pubblicazione delegata.
Sessione e passkey dell’approvatore	Pagina di approvazione	Approvare o rifiutare una verifica di rilascio vincolata al checksum.
Identità Cloudflare Access	Console dell’operatore	Operare il servizio ospitato. Non rappresenta un pubblicatore o approvatore.

Il servizio memorizza separatamente gli stati del pubblicatore e dell’approvatore. Accedere per visualizzare i propri rilasci non concede l’accesso operatore, e un’identità operatore non può approvare un rilascio come pubblicatore.

Comportamento dell’Action

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

Il workflow standard generato fornisce questi input:

Input	Valore
`service-url`	Origine HTTPS del servizio di rilascio.
`publisher-did`	DID proprietario del profilo del pacchetto e dei rilasci.
`connection-invitation`	`EMDASH_CONNECTION_INVITATION` alla prima connessione.
`bundle-file`	Il singolo tarball prodotto da `emdash-plugin bundle`.
`provenance-file`	Output grezzo `bundle-path` da `actions/attest-build-provenance`.

L’Action restituisce questi output:

Output	Significato
`connection-url`	URL browser per l’approvazione del workflow alla prima esecuzione.
`intent-id`	Identificatore dell’intento di rilascio.
`state`	Stato Published, terminale o `awaiting_approval`.
`approval-url`	URL browser quando è richiesta l’approvazione passkey.
`release-uri`	URI AT del rilascio pubblicato.
`release-cid`	CID del record di rilascio pubblicato.
`reason-code`	Motivo stabile per un intento terminale.

Consulta il riferimento dell’Action per input opzionali, workflow di sorgente URL personalizzati, controlli di polling e comportamento esatto dell’output.

Risoluzione dei problemi

`PACKAGE_PROFILE_REQUIRED`

Il profilo del pacchetto è assente, manca di impostazioni di rilascio delegato, utilizza un URL di repository non canonico o nomina un repository diverso dal workflow GitHub.

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

pnpm exec emdash-plugin profile setup

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

Repository pubblico richiesto

GitHub utilizza una root di fiducia Sigstore privata per i repository privati e interni. Il verificatore di rilascio attualmente si affida solo alla provenienza GitHub pubblica. Sposta il workflow di rilascio in un repository pubblico o pubblica localmente con emdash-plugin publish.

Invito scaduto o non valido

Crea un altro invito nella dashboard dei rilasci e sostituisci EMDASH_CONNECTION_INVITATION. Avvia il workflow entro 30 minuti. Un invito è monouso e limitato a un ID plugin.

`WORKLOAD_NOT_ALLOWED`

Il repository GitHub, proprietario, file workflow, ref o ambiente non corrisponde alla politica del workflow approvato. Apri la dashboard dei rilasci e approva una nuova connessione del workflow con lo scope previsto.

`PROFILE_FETCH_FAILED`

Il servizio non ha potuto verificare il profilo dal PDS del pubblicatore. Riprova quando il fornitore 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 l’approvazione del workflow, l’approvazione del rilascio o la pubblicazione fosse completata. Controlla lo stato dell’intento nella dashboard dei rilasci prima di rieseguire. Una riesecuzione della stessa esecuzione GitHub Actions riutilizza la sua chiave di idempotenza.

Revocare la pubblicazione automatizzata

Seleziona Turn off automated publishing nella dashboard dei rilasci. La revoca cancella la delegazione di rilascio conservata. I profili dei pacchetti esistenti, i rilasci, le etichette di moderazione, i plugin installati e il login alla dashboard non cambiano.

Riconnetti la pubblicazione e approva nuovamente il workflow prima del prossimo rilascio automatizzato.

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 rivisti durante l’approvazione del rilascio e l’installazione.
The plugin registry spiega la scoperta, la moderazione e la verifica dell’installazione.