Vytvoření vlastní akce GitHubu

8 min

GitHub Actions je výkonná funkce, která vám pomůže přejít z kódu do cloudu– od pohodlí a pohodlí vašeho vlastního úložiště. Tady se dozvíte o různých typech akcí GitHubu a o metadatech, syntaxi a příkazech pracovního postupu pro vytvoření vlastních akcí GitHubu.

Typy akcí GitHubu

Diagram znázorňuje tři typy GitHub Actions; Akce kroků spuštění Dockeru, JavaScriptu a složených kroků spuštění

Akce jsou jednotlivé úkoly, které můžete použít k přizpůsobení vývojových pracovních postupů. Vlastní akce můžete vytvořit tak, že napíšete vlastní kód, který komunikuje s vaším úložištěm pro provádění vlastních úloh, nebo pomocí akcí sdílených složek komunity GitHubu. Při procházení různých akcí si všimnete, že existují tři různé typy akcí: akce kontejneru Dockeru, akce JavaScriptu a akce složených kroků spuštění. Pojďme se podrobněji podívat na jednotlivé typy akcí.

Akce kontejneru Dockeru

Kontejnery Dockeru zabalí prostředí pomocí kódu GitHub Actions. To znamená, že akce běží v konzistentním a spolehlivém prostředí, protože všechny jeho závislosti jsou v daném kontejneru. Pokud se akce musí spouštět v konkrétní konfiguraci prostředí, kontejnery Dockeru jsou dobrým způsobem, jak přejít, protože můžete přizpůsobit operační systém a nástroje. Nevýhodou je, že protože úloha musí sestavit a načíst kontejner, akce kontejneru Dockeru jsou často pomalejší než akce JavaScriptu.

Před vytvořením akce kontejneru Dockeru byste měli mít základní znalosti o tom, jak používat proměnné prostředí a systém souborů kontejneru Dockeru. Kroky k sestavení akce kontejneru Dockeru jsou pak minimální a jednoduché:

Vytvořte příkazy Dockerfile pro definování příkazů pro sestavení image Dockeru.
Vytvořte action.yml soubor metadat, který definuje vstupy a výstupy akce. runs: using: Nastavte hodnotu na docker hodnotu a runs: image: hodnotu v Dockerfile souboru.
Vytvořte entrypoint.sh soubor pro popis image Dockeru.
Potvrďte a odešlete akci na GitHub s následujícími soubory: action.yml, entrypoint.sh, Dockerfilea README.md.

Akce JavaScriptu

Akce JavaScriptu se můžou spouštět přímo na počítači spouštěče a oddělit kód akce od prostředí, které se používá ke spuštění akce. Z tohoto důvodu je kód akce zjednodušený a může provádět rychleji než akce v kontejneru Dockeru.

Jako předpoklad pro vytváření a používání zabalených akcí JavaScriptu je potřeba stáhnout Node.js, která zahrnuje npm. Jako volitelný krok (ale doporučujeme) je použít sadu nástrojů GitHub Actions Node.js, což je kolekce balíčků Node.js, které umožňují rychle vytvářet akce JavaScriptu s větší konzistencí.

Postup sestavení akce JavaScriptu je minimální a jednoduchý:

Vytvořte soubor metadat, který action.yml definuje vstupy a výstupy akce, a také informovat spouštěče akcí, jak spustit tuto akci JavaScriptu.
Vytvořte soubor s kontextovými index.js informacemi o balíčcích Toolkit, směrování a dalších funkcích akce.
Potvrďte a odešlete akci na GitHub s následujícími soubory: action.yml, index.js, package.jsonnode_modules, package-lock.jsona README.md.

Akce složených kroků spuštění

Akce složených kroků spuštění umožňují opakovaně používat akce pomocí skriptů prostředí. V rámci stejné akce můžete dokonce kombinovat více jazyků prostředí. Pokud máte mnoho skriptů prostředí pro automatizaci několika úloh, můžete je teď snadno převést na akci a znovu je použít pro různé pracovní postupy. Někdy je jednodušší jednoduše napsat skript prostředí než pomocí JavaScriptu nebo zabalit kód do kontejneru Dockeru.

Metadata a syntaxe potřebná k vytvoření akce

Při vytváření nebo kontrole akce GitHubu je skvělým prvním krokem zkontrolovat soubor a posoudit action.yml , které vstupy, výstupy, popis, spuštění a další informace o konfiguraci, které akce potřebuje. Některé z těchto parametrů jsou povinné, zatímco jiné jsou volitelné. Soubor action.yml definuje následující informace o vaší akci:

Parametr	Popis	Povinní účastníci
Název	Název akce. Pomáhá vizuálně identifikovat akci v úloze.	ano
Popis	Shrnutí toho, co vaše akce dělá.	ano
Vstupy	Vstupní parametry umožňují zadat data, která akce očekává během běhu. Tyto parametry se ve spouštěči stanou proměnnými prostředí.	ne
Výstupy	Výstupní parametry umožňují zadat data, která následující akce mohou později použít v pracovním postupu po akci, která definuje spuštění těchto výstupů.	ne
Spuštění	Příkaz, který se má spustit při spuštění akce.	ano
Značka	Barva a ikona Feather, která se má použít k vytvoření odznáčku pro přizpůsobení a odlišení akce na GitHub Marketplace	ne

Vstupy

Vstupy jsou parametry, které umožňují zadat data, která akce očekává během běhu. GitHub ukládá tyto vstupní parametry jako proměnné prostředí.

Následuje příklad seznamu vstupů pro akci. Vstup firstNameStudent je nepovinný, zatímco je vyžadován vstup studentGrade .

inputs:
  firstNameStudent:
    description: 'First name of student'
    required: false
    default: '1'
  studentGrade:
    description: 'Grade of the student'
    required: true

Výstupy

Výstupy jsou parametry, které umožňují deklarovat data. Mějte na paměti, že akce, které se spustí později v pracovním postupu, můžou používat výstupní data deklarovaná v dříve spuštěné akci.

Následující příklad je jednoduchý výstup, který deklaruje průměrnou známku studentů:

outputs:
  average:
    description: 'The average grade of the students'

Spuštění

Jak jste se dozvěděli dříve, vaše akce musí mít runs příkaz, který definuje příkaz potřebný k provedení akce. V závislosti na tom, jak vytváříte akci – bez ohledu na to, jestli používáte kontejner Dockeru, JavaScript nebo složené kroky spuštění – runs se syntaxe definuje jinak.

`runs` pro akce Dockeru

Akce kontejneru Dockeru runs vyžadují příkaz ke konfiguraci image, která akce Dockeru používá, s následujícími argumenty:

using: Je potřeba nastavit, aby docker se spustila akce kontejneru Dockeru.
image: Image Dockeru používaná jako kontejner ke spuštění akce

runs:
  using: 'docker'
  image: 'Dockerfile'

`runs` pro akce JavaScriptu

Akce JavaScriptu runs vyžadují, aby příkaz vyžadoval následující dva argumenty:

using: Aplikace použitá ke spuštění kódu definovaného v main
main: Soubor obsahující kód akce; aplikace definovaná v using tomto souboru

Tady je například runs příkaz pro akci JavaScriptu pomocí Node.js:

runs:
  using: 'node12'
  main: 'main.js'

`runs` pro akce složených kroků spuštění

Akce složených kroků spuštění vyžadují, aby runs příkaz podnikl následující tři argumenty:

using: Je potřeba nastavit, aby "composite" se spustil složený krok spuštění.
steps: Spuštění kroků pro spuštění akce
steps[*].run: Příkaz, který chcete spustit (může být vložený nebo skript v úložišti akcí)

Tady runs je například příkaz pro akci složeného postupu spuštění, která spustí skript v cestě k /test/script/shsouboru:

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

Značka

Volitelná, ale zábavná funkce je možnost přizpůsobit odznáček vaší akce. Odznáček se zobrazí vedle názvu akce na GitHub Marketplace. K vytvoření odznáčku můžete použít barvu a ikonu Feather . U brandingu budete muset zadat ikonu a barvu, kterou chcete použít.

branding:
  icon: 'shield'  
  color: 'blue'

Tady je příklad odznaku akce rezervace na GitHub Marketplace:

Snímek obrazovky znázorňující branding akce na GitHub Marketplace

Příkazy pracovního postupu

Vytvoření pracovního postupu je poměrně jednoduché, pokud najdete správné akce pro kroky. V některých případech možná budete muset vytvořit vlastní akce, abyste dosáhli požadovaných výsledků, ale pomocí příkazů pracovního postupu můžete přidat další úroveň přizpůsobení pracovních postupů.

Příkazy pracovního postupu umožňují komunikovat s počítačem GitHub Actions Runner tiskem naformátovaných řádků textu do konzoly. Tyto příkazy pracovního postupu můžete použít s příkazy prostředí nebo ve vlastních akcích. Příkazy pracovního postupu jsou užitečné, protože umožňují sdílet informace mezi kroky pracovního postupu, tisknout ladicí nebo chybové zprávy do konzoly, nastavit proměnné prostředí, nastavit výstupní parametry nebo přidat do systémové cesty.

Většina příkazů pracovního postupu používá echo tento příkaz v následujícím konkrétním formátu, zatímco jiné je možné vyvolat zápisem do souboru:

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

Následuje několik základních příkladů protokolování zpráv pro tisk ladicí zprávy, informační zprávy, chybové zprávy nebo upozornění na konzolu:

- name: workflow commands logging messages
  run: |
    echo "::debug::This is a debug message"
    echo "This is an info message"
    echo "::error::This is an error message"
    echo "::warning::This is a warning message"

Můžete také vytvořit zprávu pro tisk do protokolu s názvem souboru (soubor), číslem řádku (řádek) a číslem sloupce (col), kde došlo k chybě. Zprávy upozornění se zobrazí ve žlutém zvýraznění s textem "upozornění" a chybové zprávy se zobrazí v červeném zvýraznění s textem "chyba".

echo "::error file=app.js,line=10,col=15::Something went wrong"

Je důležité si uvědomit, že tyto příkazy pracovního postupu musí být na jednom řádku. Znaky, které kolidují s analýzou, jako jsou čárky a konce řádků, musí být kódované adresou URL.

Například následující text je víceřádkové zprávy:

This text spans
across multiple lines

Tato zpráva by měla být zakódovaná, jak je znázorněno tady:

This text spans%0Aacross multiple lines

Kromě příkazů pracovního postupu můžete nastavit ukončovací kódy pro nastavení stavu akce. To je důležité, protože když pracujete s úlohami v pracovním postupu, ukončovací kód, který selhal, zastaví všechny souběžné akce a zruší všechny budoucí akce. Pokud vytváříte akci JavaScriptu, můžete pomocí balíčku actions toolkit @actions/core protokolovat zprávu a nastavit ukončovací kód selhání. Pokud vytváříte akci kontejneru Dockeru, můžete ve entrypoint.sh skriptu nastavit ukončovací kód selhání.