Egyéni GitHub-művelet közzététele

  • 6 perc

Itt megismerkedhet a művelet megfelelő láthatóságának kiválasztásával, a művelet dokumentálásával és verziószámozásával kapcsolatos ajánlott eljárásokkal, valamint a művelet GitHub Marketplace-en való közzétételével.

A művelet helyének kiválasztása

Egy művelet két láthatósági beállítását megjelenítő diagram: nyilvános vagy privát.

Egy művelet létrehozásakor fontos először eldönteni, hogy hol szeretné élni a műveletet, és a művelet láthatóságát, legyen az public vagy private. A művelet láthatósága határozza meg, hogy mely javaslatokra és követelményekre van szükség a művelet kiadásához. Tekintsük át közelebbről ezt a két láthatósági lehetőséget.

Nyilvános

Bármely adattár munkafolyamatai használhatnak nyilvános műveleteket. Ha egy műveletet azzal a szándékkal fejleszt, hogy nyílt forráskód vagy nyilvánosan elérhetővé tegye a GitHub Marketplace-en keresztül, javasoljuk (és a legtöbb esetben kötelező), hogy a művelet saját adattárral rendelkezik ahelyett, hogy más alkalmazáskóddal lenne összekapcsolva. Ez lehetővé teszi a műveletet ugyanúgy verziószámozhatja, követheti nyomon és szabadíthatja fel, mint bármely más szoftvert. Ez megkönnyíti a GitHub-közösség számára a művelet felderítését, szűkíti a kódbázis hatókörét a problémák megoldásához és a művelet kiterjesztéséhez, és elkülöníti a művelet verziószámozását a többi alkalmazáskód verziószámozásától.

Személyes

Ha egy művelet privát adattárban van, csak az ugyanabban az adattárban lévő munkafolyamatok használhatják a műveletet. Privát műveletek esetén a művelet fájljait az adattár bármely pontján tárolhatja. Ha egyetlen adattárban szeretné kombinálni a műveletet, a munkafolyamatot és az alkalmazáskódot, javasoljuk, hogy tárolja a műveletet a .github címtárban. Például: .github/actions/action-a és .github/actions/action-b.

A művelet dokumentálása

Nagyon frusztráló lehet egy új eszköz vagy alkalmazás használata, ha a dokumentáció homályos, vagy akár hiányzik is. Fontos, hogy a művelethez jó dokumentációt mellékeljen, hogy mások is láthassák, hogyan működik, akár nyilvánossá vagy privátsá szeretné tenni. Első lépésként hozzon létre egy jó README.md fájlt a művelethez.

A README.md fájl gyakran az első hely, ahol a fejlesztők megtekintik a művelet működését. Ez egy nagyszerű hely, ahol a művelethez szükséges összes fontos információt belefoglalhatja. Az alábbiakban felsoroljuk a következőket:

  • A művelet végrehajtásának részletes leírása.
  • Kötelező bemeneti és kimeneti argumentumok.
  • Nem kötelező bemeneti és kimeneti argumentumok.
  • A művelet által használt titkos kódok.
  • A művelet által használt környezeti változók.
  • Példa a művelet munkafolyamatban való használatára.

Általában a README.md fájlnak tartalmaznia kell mindent, amit a felhasználónak tudnia kell a művelet használatához. Ha úgy gondolja, hogy hasznos információ lehet, vegye fel a README.md.

A művelet kiadása és verziója

Ha olyan műveletet fejleszt, amelyet mások is használhatnak, legyen az nyilvános vagy privát, a frissítések terjesztésének szabályozására egy kiadáskezelési stratégiát kell meghatároznia. A főbb verziófrissítéseket, beleértve a szükséges kritikus javításokat és a kompatibilitást befolyásoló biztonsági javításokat, egyértelműen dokumentálni kell.

Ajánlott eljárások a kiadáshoz és a verziókezeléshez

A jó kiadáskezelési stratégiának verziószámozási javaslatokat kell tartalmaznia. A felhasználók nem hivatkozhatnak a művelet alapértelmezett ágára a művelettel. Ennek az az oka, hogy az alapértelmezett ág, amely valószínűleg a legújabb kódot tartalmazza (ami lehet, hogy nem stabil), a munkafolyamat megszakadását okozhatja. Ehelyett azt javasoljuk, hogy a felhasználók a művelet használatakor adjanak meg egy főverziót, és csak akkor irányítsák őket egy konkrétabb verzióra, ha problémákat tapasztalnak. Ezt úgy tehetik meg, hogy konfigurálják a GitHub Actions-munkafolyamatot egy címke, egy véglegesítés sha-jának vagy egy kiadáshoz elnevezett adott ág megcélzásához. Nézzük meg közelebbről ezeket a kiadási lehetőségeket.

Címkék

A címkék jó módot jelenthetnek a műveletek kiadásainak kezelésére. Címkék használatával a felhasználók könnyen megkülönböztethetik a főverziókat és az alverziókat. Az alábbiakban felsoroljuk azokat a hasznos eljárásokat, amelyeket érdemes megfontolni a kiadások létrehozásakor:

  • Kiadás létrehozása és érvényesítése egy kiadási ágon (például release/v1) a kiadási címke létrehozása előtt (például v1.0.2).
  • Használjon szemantikai verziószámozást.
  • Helyezze át a főverzió címkéjét (például v1, v2) az aktuális kiadás Git-refjére mutatva.
  • Új főverziócímke (v2) bevezetése a meglévő munkafolyamatokat megszakító módosításokhoz.
  • A főverziók bétacímkével való kiadása állapotuk jelzésére; például v2-beta. Ha a -beta kiadás elkészült, eltávolíthatja a címkét.

Íme néhány példa az egyes lehetőségekre.

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

Véglegesítés sha-jának használata

A címkék hasznosak és széles körben használhatók, de a címkék használatának egyik hátránya, hogy törölhetők vagy áthelyezhetők. A Git használatával minden véglegesítés kap egy számított SHA-értéket, amely egyedi, és nem módosítható. A véglegesítési SHA verziószámozáshoz való használata biztosítja a legmegbízhatóbb és legbiztonságosabb módot a verziószámozásra és a műveletek használatára. A Gitben azonban gyakran rövidítheti az SHA kivonatot az első néhány karakterre, és a Git felismeri a hivatkozást. Ha a véglegesítés SHA-ját használja a kiadáskezeléshez, a teljes SHA-értéket kell használnia, nem pedig a rövidített értéket.

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

Művelet közzététele a GitHub Marketplace-en

A GitHub Marketplace-t ábrázoló renderelés, eszközök, amelyekkel javíthatja és kialakíthatja a munkafolyamatát.

Ha készen áll arra, hogy megossza a műveletet a GitHub-közösséggel, közzéteheti a GitHub Marketplace-en, és több millió GitHub-felhasználót érhet el. A GitHub Marketplace-en közzétett műveletek azonnal közzé lesznek téve, ha az összes követelmény teljesül. A követelményeknek nem megfelelő műveleteket a GitHubnak ellenőriznie kell a közzététel előtt. Gondoskodnia kell arról, hogy az adattár csak a művelethez szükséges metaadatfájlokat, kódot és fájlokat tartalmazza. Egyetlen adattár létrehozása a művelethez lehetővé teszi a kód címkézését, kiadását és csomagolását egyetlen egységben. A GitHub a művelet metaadatait is használja a GitHub Marketplace-oldalán.

Az alábbiakban a műveletet a GitHub Marketplace-en közzétevő követelményeket követjük. A Docker-tárolóalapú és a JavaScript-alapú műveletekre egyaránt érvényesek:

  • A műveletnek nyilvános adattárban kell lennie.
  • Minden adattárnak egyetlen műveletet kell tartalmaznia.
  • A művelet metaadatfájljának (action.yml vagy action.yaml) az adattár gyökérkönyvtárában kell lennie.
  • A name művelet metaadatfájljának egyedinek kell lennie a GitHub Marketplace-en.
    • A név nem egyezhet meg egy felhasználóval vagy szervezettel a GitHubon, kivéve, ha a felhasználó vagy a szervezet tulajdonosa közzéteszi a műveletet. Például csak a GitHub-szervezet tehet közzé egy műveletet.github
    • A name nem egyezik meg egy meglévő GitHub Marketplace-kategóriával.
    • A name nem egyezik egy meglévő GitHub-funkcióval.

A létrehozott műveletet hozzáadhatja a GitHub Marketplace-hez úgy, hogy új kiadásként megjelöli, majd közzéteszi. A GitHubon néhány irányított lépéssel közzéteheti a műveletet. Ezekről a lépésekről a modul végén található Összegzés szakaszban talál további információt.