Pubblicare un'azione di GitHub personalizzata

Questa sezione contiene le informazioni sulla scelta della visibilità appropriata per l'azione, sulle procedure consigliate per documentare ed eseguire il controllo delle versioni dell'azione e su come pubblicare l'azione nel marketplace di GitHub.

Scegliere una posizione per l'azione

Quando si crea un'azione, è importante decidere prima dove si vuole rendere disponibile l'azione e la sua visibilità, che sia public o private. La visibilità dell'azione determina quali elementi consigliati e requisiti sono necessari per rilasciare l'azione. Ora verranno esaminate più approfonditamente queste due opzioni di visibilità.

Pubblico

I flussi di lavoro in qualsiasi repository possono usare azioni pubbliche. Se si sviluppa un'azione con la finalità di renderla open source o di renderla pubblicamente disponibile tramite il marketplace di GitHub, è consigliabile, e nella maggior parte dei casi è obbligatorio, che l'azione abbia un proprio repository anziché aggregarla al codice di un'altra applicazione. In questo modo è possibile eseguire il controllo della versione, tenere traccia e rilasciare l'azione come si fa per un qualsiasi altro componente software. In questo modo la community di GitHub può individuare più facilmente l'azione, si restringe l'ambito del codebase per gli sviluppatori che correggono i problemi ed estendono l'azione, e si separa il controllo delle versioni dell'azione dal controllo delle versioni del codice dell'applicazione.

Privata

Quando un'azione si trova in un repository privato, solo i flussi di lavoro dello stesso repository possono utilizzare l'azione. Con le azioni private è possibile archiviare i file dell'azione in una posizione qualsiasi del repository. Se si prevede di combinare l'azione, il flusso di lavoro e il codice dell'applicazione in un singolo repository, è consigliabile archiviare l'azione nella directory .github. Ad esempio, .github/actions/action-a e .github/actions/action-b.

Documentare l'azione

Può essere difficile usare un nuovo strumento o una nuova applicazione quando la documentazione è vaga o addirittura assente. È importante includere una buona documentazione con l'azione in modo che gli altri utenti possano sapere come funziona, sia si prevede di renderla pubblica o privata. La prima cosa da fare è creare un file di README.md valido per l'azione.

Il file README.md è spesso l'elemento che gli sviluppatori esaminano per primo per vedere come funziona l'azione. È l'elemento ideale per includere tutte le informazioni importanti sull'azione. Di seguito è riportato un elenco non esaustivo delle cose da includere:

• Descrizione dettagliata delle operazioni dell'azione.
• Argomenti di input e output obbligatori.
• Argomenti di input e output facoltativi.
• Segreti usati dall'azione.
• Variabili di ambiente usate dall'azione.
• Esempio di come usare l'azione in un flusso di lavoro.

Come regola generale, il file README.md deve includere tutto ciò che un utente deve sapere per usare l'azione. Se si pensa che un'informazione potrebbe essere utile, includerla in README.md.

Rilasciare ed eseguire il controllo della versione dell'azione

Se si sviluppa un'azione che potrà essere usata da altri utenti, indipendentemente che sia pubblica o privata, è consigliabile definire una strategia di gestione del rilascio per controllare la modalità di distribuzione degli aggiornamenti. Gli aggiornamenti delle versioni principali, incluse le correzioni critiche necessarie e le patch di sicurezza che influiscono sulla compatibilità, devono essere documentati in modo chiaro.

Procedure consigliate per la gestione delle versioni e del rilascio

Una buona strategia di gestione del rilascio deve includere gli elementi consigliati sul controllo delle versioni. Gli utenti non devono fare riferimento al ramo predefinito di un'azione con l'azione. Ciò è dovuto al fatto che il ramo predefinito che probabilmente contiene il codice più recente (che potrebbe o potrebbe non essere stabile) potrebbe causare un'interruzione del flusso di lavoro. È invece consigliabile che gli utenti specifichino una versione principale quando usano l'azione e che vengano indirizzati a una versione più specifica solo in caso di problemi. È possibile farlo configurando il flusso di lavoro di GitHub Actions affinché abbia come destinazione un tag, l'SHA di un commit o un ramo specifico denominato per una versione. Tali opzioni di rilascio vengono ora esaminate più in dettaglio.

Tag

I tag possono essere un ottimo strumento per gestire le versioni di un'azione. Con i tag gli utenti possono distinguere facilmente tra le versioni principali e secondarie. Di seguito è riportato un elenco di procedure utili da prendere in considerazione durante la creazione delle versioni:

• Creare e convalidare una versione in un ramo di versione (ad esempio release/v1) prima di creare il tag di versione (ad esempio, v1.0.2).
• Usare il Versionamento Semantico.
• Spostare il tag della versione principale (ad esempio v1, v2) in modo che punti al riferimento Git della versione corrente.
• Introdurre un nuovo tag della versione principale (v2) per le modifiche che interromperanno i flussi di lavoro esistenti.
• Rilasciare le versioni principali con un tag beta che ne indichi lo stato; ad esempio v2-beta. È possibile rimuovere il tag -beta quando la versione è pronta.

Ecco alcuni esempi di ciascuna opzione.

steps:
    - uses: actions/javascript-action@v1
    - uses: actions/javascript-action@v1.0.1
    - uses: actions/javascript-action@v1-beta

Usare l'SHA di un commit

I tag sono utili e ampiamente usati, ma uno svantaggio quando li si usa è che possono essere eliminati o spostati. Con Git, ogni commit riceve un valore SHA calcolato, univoco e non può essere modificato. L'uso dell'SHA di un commit per il controllo delle versioni consente di eseguire il controllo delle versioni e di usare un'azione nel modo più affidabile e sicuro. Tuttavia, è spesso possibile abbreviare l'hash SHA in Git usando i primi caratteri e Git riconoscerà il riferimento. Se si usa l'SHA del commit per la gestione del rilascio, è necessario usare il valore SHA completo e non il valore abbreviato.

steps:
    - uses: actions/javascript-action@2522385f6f7ba04fe7327647b213799853a8f55c

Pubblicare un'azione nel marketplace di GitHub

Quando si è pronti per condividere l'azione con la community di GitHub, è possibile pubblicarla nel marketplace di GitHub e raggiungere milioni di utenti. Le azioni vengono pubblicate immediatamente nel marketplace di GitHub se sono soddisfatti tutti i requisiti. Le azioni che non soddisfano i requisiti devono essere esaminate da GitHub prima della pubblicazione. È necessario assicurarsi che il repository includa solo il file di metadati, il codice e i file necessari per l'azione. La creazione di un unico repository per l'azione permette di contrassegnare, rilasciare e creare il pacchetto del codice in un'unica unità. GitHub usa anche i metadati dell'azione nella pagina del marketplace.

Di seguito sono riportati i requisiti per pubblicare un'azione nel marketplace di GitHub. Si applicano sia alle azioni basate su contenitori Docker che alle azioni basate su JavaScript:

• L'azione deve trovarsi in un repository pubblico.
• Ogni repository deve contenere un'unica azione.
• Il file di metadati dell'azione (action.yml o action.yaml) deve essere nella directory radice del repository.
• Il valore di name nel file di metadati dell'azione deve essere univoco nel marketplace di GitHub.
  • Il nome non può corrispondere a un utente o a un'organizzazione in GitHub, a meno che l'azione non venga pubblicata dall'utente o dal proprietario dell'organizzazione. Ad esempio, solo l'organizzazione GitHub può pubblicare un'azione denominata github.
  • Il valore di name non può corrispondere a una categoria esistente nel marketplace di GitHub.
  • Il valore di name non può corrispondere a una funzionalità esistente di GitHub.

È possibile aggiungere l'azione creata al marketplace di GitHub contrassegnandola come nuova versione e quindi pubblicandola. Alcuni passaggi guidati di GitHub permettono di pubblicare una versione dell'azione. Per ulteriori informazioni su questi passaggi, consultare la sezione Riepilogo alla fine di questo modulo.