Publikování vlastní akce GitHubu

Dokončeno

Tady se dozvíte o výběru správné viditelnosti pro vaši akci, osvědčených postupech pro dokumentaci a správu verzí akce a o tom, jak publikovat akci na GitHub Marketplace.

Volba umístění pro vaši akci

Při vytváření akce je důležité nejprve rozhodnout, kde má tato akce existovat, a viditelnost této akce, ať už bude public nebo private. Viditelnost akce určuje, která doporučení a požadavky jsou potřeba k vydání této akce. Pojďme se podrobněji podívat na tyto dvě možnosti viditelnosti.

Veřejná

Pracovní postupy v libovolném úložišti můžou používat veřejné akce. Pokud vyvíjíte akci s záměrem, aby byla opensourcová nebo veřejně přístupná prostřednictvím GitHub Marketplace, doporučujeme (a ve většině případů je potřeba) mít akce vlastní úložiště, a nemusíte ji spojování s jiným kódem aplikace zařazuje. Díky tomu můžete akci vydávat, sledovat a vydávat stejně jako jakoukoli jinou část softwaru. To usnadňuje komunitě GitHubu zjišťování akce, zužuje rozsah základu kódu pro vývojáře, řeší problémy a rozšiřuje akci a odděluje správu verzí akce od správy verzí jiného kódu aplikace.

Privátní

Když je akce v privátním úložišti, můžou tuto akci použít jenom pracovní postupy ve stejném úložišti. Pomocí soukromých akcí můžete soubory akce uložit do libovolného umístění ve vašem úložišti. Pokud plánujete kombinovat akce, pracovní postup a kód aplikace v jednom úložišti, doporučujeme uložit akci do .github adresáře. Příklad: .github/actions/action-a a .github/actions/action-b.

Zdokumentujte akci

Použití nového nástroje nebo aplikace může být velmi frustrující, pokud je dokumentace vágní nebo dokonce chybí. Je důležité zahrnout do akce dobrou dokumentaci, aby ostatní viděli, jak to funguje, ať už plánujete, aby byla veřejná nebo soukromá. První věcí, kterou je potřeba udělat, je vytvoření vhodného README.md souboru pro vaši akci.

Soubor README.md je často prvním místem, kde vývojáři uvidí, jak akce funguje. Toto je skvělé místo pro zahrnutí všech důležitých informací pro akci. Následuje seznam věcí, které je třeba zahrnout:

• Podrobný popis toho, co akce dělá
• Požadované vstupní a výstupní argumenty
• Volitelné vstupní a výstupní argumenty
• Tajné kódy, které akce používá
• Proměnné prostředí, které akce používá
• Příklad použití akce v pracovním postupu

Obecně platí, že soubor by měl obsahovat vše, README.md co by měl uživatel vědět, aby akci používal. Pokud si myslíte, že by to mohly být užitečné informace, zahrňte je do souboru README.md.

Vydání a verze akce

Pokud vyvíjíte akci pro ostatní uživatele, kteří ji budou používat, ať už je veřejná nebo soukromá, měli byste definovat strategii správy vydaných verzí pro řízení způsobu distribuce aktualizací. Aktualizace hlavní verze, včetně nezbytných důležitých oprav a oprav zabezpečení, které ovlivňují kompatibilitu, je potřeba jasně zdokumentovat.

Osvědčené postupy pro správu verzí a verzí

Dobrá strategie správy verzí by měla obsahovat doporučení pro správu verzí. Uživatelé by neměli odkazovat na výchozí větev akce s akcí, protože výchozí větev, která bude pravděpodobně obsahovat nejnovější kód (což může nebo nemusí být stabilní) a může vést k narušení pracovního postupu. Místo toho doporučujeme, aby uživatelé při použití akce zadali hlavní verzi a aby je při výskytu problémů nasměrovali jenom na konkrétnější verzi. Můžou to udělat tak, že nakonfigurují pracovní postup GitHub Actions tak, aby cílil na značku, SHA potvrzení nebo konkrétní větev pojmenovanou pro vydání. Pojďme se podrobněji podívat na tyto možnosti vydání.

Značky

Značky můžou být dobrým způsobem, jak spravovat vydané verze pro akci. Pomocí značek můžou uživatelé snadno rozlišovat mezi hlavními a podverzemi. Tady je seznam užitečných postupů, které je potřeba vzít v úvahu při vytváření verzí:

• Vytvoření a ověření verze ve větvi vydané verze (například release/v1) před vytvořením značky vydané verze (například v1.0.2).
• Používejte sémantickou správu verzí.
• Přesuňte značku hlavní verze (například v1) tak, v2aby odkaz na odkaz Gitu aktuální verze.
• Zavedení nové značky hlavní verze (v2) pro změny, které přeruší stávající pracovní postupy.
• Vydání hlavních verzí se značkou beta, která označuje jejich stav; například v2-beta. Značku můžete odebrat -beta , až bude vydaná verze připravená.

Tady je několik příkladů jednotlivých možností.

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

Použití sha potvrzení

Značky jsou užitečné a široce používané, ale jednou nevýhodou použití značek je, že je možné je odstranit nebo přesunout. U Gitu obdrží každé potvrzení počítanou hodnotu SHA, která je jedinečná a nelze ji změnit. Použití algoritmu SHA potvrzení pro správu verzí vám poskytne nejspolehlivější a nejbezpečnější způsob, jak provést verzi a použít akci. Často ale v Gitu můžete zkrátit hodnotu hash SHA na několik prvních znaků a Git odkaz rozpozná. Pokud používáte sha potvrzení pro správu verzí, musíte použít úplnou hodnotu SHA, nikoli zkrácenou hodnotu SHA.

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

Publikování akce na GitHub Marketplace

Až budete připraveni sdílet svoji akci s komunitou GitHubu, můžete ji publikovat na GitHub Marketplace a kontaktovat miliony uživatelů GitHubu. Akce publikované na GitHub Marketplace se publikují okamžitě, pokud jsou splněny všechny požadavky. Akce, které nesplňují požadavky, musí GitHub před publikováním zkontrolovat. Budete muset zajistit, aby úložiště obsahovalo pouze soubor metadat, kód a soubory potřebné pro danou akci. Vytvoření jednoho úložiště pro akci umožňuje označit, uvolnit a zabalit kód do jedné jednotky. GitHub také používá metadata akce na stránce GitHub Marketplace.

Následují požadavky na publikování akce na GitHub Marketplace. Platí pro akce založené na kontejnerech Dockeru i akce založené na JavaScriptu:

• Akce musí být ve veřejném úložišti.
• Každé úložiště musí obsahovat jednu akci.
• Soubor metadat akce (action.yml nebo action.yaml) musí být v kořenovém adresáři úložiště.
• Soubor name metadat akce musí být na GitHub Marketplace jedinečný.
  • Jméno nemůže odpovídat uživateli nebo organizaci na GitHubu, pokud uživatel nebo vlastník organizace akci nepublikuje. Například pouze organizace GitHubu může publikovat akci s názvem github.
  • Nejde name se shodovat s existující kategorií GitHub Marketplace.
  • Nemůže name odpovídat existující funkci GitHubu.

Akci, kterou jste vytvořili na GitHub Marketplace, můžete přidat tak, že ji označíte jako novou verzi a pak ji publikujete. Na GitHubu je několik kroků s asistencí, které vám umožní publikovat verzi akce. Další informace o těchto krocích najdete v části Souhrn na konci tohoto modulu.