Publicera en anpassad GitHub-åtgärd

• 6 minuter

Här får du lära dig hur du väljer rätt synlighet för din åtgärd, metodtips för att dokumentera och versionshantera din åtgärd och hur du publicerar din åtgärd på GitHub Marketplace.

Välj en plats för åtgärden

När du skapar en åtgärd är det viktigt att först bestämma var du vill att åtgärden ska leva och synligheten för den åtgärden, om den ska vara public eller private. Åtgärdens synlighet avgör vilka rekommendationer och krav som krävs för att släppa åtgärden. Nu ska vi titta närmare på de här två synlighetsalternativen.

Offentliga

Arbetsflöden på valfri lagringsplats kan använda offentliga åtgärder. Om du utvecklar en åtgärd med avsikten att göra den öppen källkod eller göra den offentligt tillgänglig via GitHub Marketplace rekommenderar vi (och i de flesta fall krävs det) att åtgärden har en egen lagringsplats i stället för att kombinera den med annan programkod. På så sätt kan du version, spåra och släppa åtgärden precis som andra programvaror. Det gör det enklare för GitHub-communityn att identifiera åtgärden, begränsar omfånget för kodbasen för utvecklare som åtgärdar problem och utökar åtgärden och separerar åtgärdens versionshantering från versionshantering av annan programkod.

Privat

När en åtgärd finns på en privat lagringsplats kan endast arbetsflöden på samma lagringsplats använda åtgärden. Med privata åtgärder kan du lagra åtgärdens filer på valfri plats på lagringsplatsen. Om du planerar att kombinera åtgärds-, arbetsflödes- och programkod på en enda lagringsplats rekommenderar vi att du lagrar åtgärden i .github katalogen. Till exempel .github/actions/action-a och .github/actions/action-b.

Dokumentera din åtgärd

Det kan vara mycket frustrerande att använda ett nytt verktyg eller program när dokumentationen är vag eller till och med saknas. Det är viktigt att inkludera bra dokumentation med din åtgärd så att andra kan se hur den fungerar, oavsett om du planerar att göra den offentlig eller privat. Det första du behöver göra är att skapa en bra README.md fil för din åtgärd.

Filen README.md är ofta den första platsen som utvecklare tittar på för att se hur åtgärden fungerar. Detta är ett bra ställe att inkludera all viktig information för åtgärden. Följande är en icke-fullständig lista över saker som ska inkluderas:

• En detaljerad beskrivning av vad åtgärden gör
• Obligatoriska argument för in- och utdata
• Valfria argument för in- och utdata
• Hemligheter som åtgärden använder
• Miljövariabler som åtgärden använder
• Ett exempel på hur du använder din åtgärd i ett arbetsflöde

Som en allmän regel README.md bör filen innehålla allt som en användare bör känna till för att använda åtgärden. Om du tror att det kan vara användbar information kan du ta med den i README.md.

Släpp och versionshantera åtgärden

Om du utvecklar en åtgärd som andra kan använda, oavsett om den är offentlig eller privat, bör du definiera en strategi för versionshantering som styr hur uppdateringar distribueras. Viktiga versionsuppdateringar, inklusive nödvändiga kritiska korrigeringar och säkerhetskorrigeringar som påverkar kompatibiliteten, måste dokumenteras tydligt.

Bra metoder för versionshantering och versionshantering

En bra strategi för versionshantering bör innehålla versionsrekommendationer. Användare bör inte referera till en åtgärds standardgren med åtgärden, eftersom standardgrenen som sannolikt innehåller den senaste koden (som kanske eller kanske inte är stabil) och kan leda till att arbetsflödet bryts. I stället rekommenderar vi att användarna anger en huvudversion när de använder åtgärden och att de endast dirigeras till en mer specifik version om de stöter på problem. De kan göra detta genom att konfigurera sitt GitHub Actions-arbetsflöde för att rikta in sig på en tagg, en inchecknings SHA eller en specifik gren med namnet för en version. Låt oss ta en närmare titt på de här versionsalternativen.

Taggar

Taggar kan vara ett bra sätt att hantera versioner för en åtgärd. Med hjälp av taggar kan användarna enkelt skilja mellan större och mindre versioner. Följande är en lista över användbara metoder att tänka på när du skapar versioner:

• Skapa och verifiera en version på en versionsgren (till exempel release/v1) innan du skapar versionstaggen (till exempel v1.0.2).
• Använd semantisk versionshantering.
• Flytta huvudversionstaggen (till exempel v1, v2) för att peka på Git-referensen för den aktuella versionen.
• Introducera en ny huvudversionstagg (v2) för ändringar som bryter befintliga arbetsflöden.
• Släpp större versioner med en betatagg för att ange deras status. till exempel v2-beta. Du kan ta bort taggen -beta när versionen är klar.

Här följer några exempel på varje alternativ.

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

Använda en inchecknings SHA

Taggar är användbara och används ofta, men en nackdel med att använda taggar är att de kan tas bort eller flyttas. Med Git får varje incheckning ett beräknat SHA-värde, som är unikt och inte kan ändras. Om du använder en inchecknings-SHA för versionshantering får du det mest tillförlitliga och säkra sättet att version och använda en åtgärd. Men ofta i Git kan du förkorta SHA-hashen till de första flera tecknen, så känner Git igen referensen. Om du använder incheckningens SHA för versionshantering måste du använda det fullständiga SHA-värdet och inte det förkortade värdet.

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

Publicera en åtgärd på GitHub Marketplace

När du är redo att dela din åtgärd med GitHub-communityn kan du publicera den på GitHub Marketplace och kontakta miljontals GitHub-användare. Åtgärder som publiceras på GitHub Marketplace publiceras omedelbart om alla krav uppfylls. Åtgärder som inte uppfyller kraven måste granskas av GitHub innan de publiceras. Du måste se till att lagringsplatsen endast innehåller metadatafilen, koden och filerna som krävs för åtgärden. När du skapar en enda lagringsplats för åtgärden kan du tagga, släppa och paketera koden i en enda enhet. GitHub använder också åtgärdens metadata på din GitHub Marketplace-sida.

Följande är kraven för att publicera en åtgärd på GitHub Marketplace. De gäller för både Docker-containerbaserade åtgärder och JavaScript-baserade åtgärder:

• Åtgärden måste finnas på en offentlig lagringsplats.
• Varje lagringsplats måste innehålla en enda åtgärd.
• Åtgärdens metadatafil (action.yml eller action.yaml) måste finnas i rotkatalogen på lagringsplatsen.
• Metadatafilen name i åtgärden måste vara unik på GitHub Marketplace.
  • Namnet kan inte matcha en användare eller organisation på GitHub, såvida inte användaren eller organisationens ägare publicerar åtgärden. Till exempel kan endast GitHub-organisationen publicera en åtgärd med namnet github.
  • Det name går inte att matcha en befintlig GitHub Marketplace-kategori.
  • Det name går inte att matcha en befintlig GitHub-funktion.

Du kan lägga till den åtgärd som du har skapat på GitHub Marketplace genom att tagga den som en ny version och sedan publicera den. Det finns några guidade steg i GitHub som gör att du kan publicera en version av åtgärden. Mer information om de här stegen finns i avsnittet Sammanfattning i slutet av den här modulen.