Praktický průvodce budováním inteligentnějších pracovních postupů GitHub

Mám poměrně dlouhou zkušenost s pracovními postupy GitHub, ale ne do té míry, že bych mohl tvrdit, že jsem odborník. nicméně, nedávno jsem vyvinul nový pracovní postup, a to mě přimělo napsat tento příspěvek. Co jsou GitHub Workflows? Pracovní postup je konfigurovatelný automatizovaný proces, který spustí jednu nebo více úkolů. Pracovní postupy jsou definovány souborem YAML, který je zapsán do úložiště a spustí se, když je spuštěna událostí ve vašem úložišti, nebo mohou být spuštěny ručně nebo podle definovaného harmonogramu. Pracovní postupy jsou definovány v adresáři .github/workflows v úložišti. úložiště může mít více pracovních postupů, z nichž každý může provádět jiný soubor úkolů, například: Vytvoření a testování požadavků na přilnutí Rozšiřování aplikace pokaždé, když je vytvořeno vydání Přidání štítku pokaždé, když se otevře nový problém O pracovních procesech A Pracovní postupy jsou definovány souborem YAML zapsaným do vašeho úložiště a budou spuštěny, když je spuštěna událostí ve vašem úložišti, nebo mohou být spuštěny ručně nebo podle definovaného harmonogramu. workflow Pracovní postupy jsou definovány v Úložisko může mít více pracovních postupů, z nichž každý může provádět jiný soubor úkolů, například: .github/workflows Vytvoření a testování požadavků na přilnutí Rozšiřování aplikace pokaždé, když je vytvořeno vydání Přidání štítku pokaždé, když se otevře nový problém O pracovních procesech Pracovní postup je tedy srovnatelný s prací Jenkins, implementovanou v YAML namísto XML. To nevypadá moc, ale umožňuje použití přístupů ke správě zdrojového kódu, včetně verzí a přepínání zpět. Před lety jsem pracoval pro zákazníka, jehož tým DevOps implementoval přístup založený na Puppetu k rekonstrukci Jenkinsových pracovních míst, takže konfigurace Puppetu mohla být uložena v Git. stored inside the code repository Všimněte si, že GitHub byl na párty poměrně pozdní.Než implementoval pracovní postupy, použil jsem službu třetí strany nazvanou Přepnul jsem se hlavně proto, že se Travis stal placeným a sekundárně proto, že pracovní postupy jsou nativně součástí GitHub. Travis se Tento tip: Jsou nazýváni GitHub akce jsou zcela odlišné. Use the correct semantics GitHub pracovní postupy GitHub akce GitHub Workflow se skládá z které se skládají Referenční kroky příkazy a několik volitelných parametrů, včetně jména. práce kroky běhání jobs: metrics: runs-on: my-image #1 steps: - name: Install dependencies via Poetry #2 run: poetry install #3 Obrázek OCI, na kterém běží workflow Jméno kroku Krok příkazu GitHub akce jsou opakovatelné komponenty, které nabízejí alternativy k opakování stejného příkazu znovu a znovu. Akce je předdefinovaná, opakovatelná sada úkolů nebo kódu, která provádí konkrétní úkoly v rámci pracovního postupu, čímž se sníží množství opakujícího se kódu, který do souborů pracovního postupu zapisujete. Vytvoření úložiště Git z GitHubu Nastavení správného řetězce nástrojů pro vaše stavební prostředí Setting up authentication for your cloud provider Můžete napsat své vlastní akce, nebo můžete najít akce pro použití ve vašich pracovních postupech v GitHub Marketplace. Například namísto provádění git checkout, můžete použít akci checkout. GitHub akce Akce je předdefinovaná, opakovatelná sada úkolů nebo kódu, která provádí konkrétní úkoly v rámci pracovního postupu, čímž se sníží množství opakujícího se kódu, který do souborů pracovního postupu zapisujete. Vytvoření úložiště Git z GitHubu Nastavení správného řetězce nástrojů pro vaše stavební prostředí Nastavení autentizace pro vašeho poskytovatele cloudových služeb Můžete napsat své vlastní akce, nebo můžete najít akce pro použití ve vašich pracovních postupech v GitHub Marketplace. Například namísto provádění git checkout, můžete použít akci checkout. GitHub akce jobs: metrics: runs-on: my-image steps: - uses: actions/checkout@v5 #1 with: #2 fetch-depth: 0 submodules: recursive Reference k akci GitHub Akční parametry Jsem velký fanoušek nevymýšlení kola znovu. GitHub Akce hrají velkou roli v tom. Tento tip: Když je to možné. Prefer GitHub Actions over ad-hoc commands Výběr správné akce Hostitel GitHub Marketplace Akce jsou uvedeny podle kategorií. Můžete filtrovat podle typu tvůrce a třídit podle popularity. Mnoho akcí Při výběru akce byste měli věnovat stejnou pozornost jako při vytváření jakékoliv jiné závislosti. Vendor: prefer verified creators License type: Open Source vs. closed source. With the former, check the exact terms; the Apache v2 license is very different from the GPL one. Pricing for commercial actions Check the source code repository of actions that display it and check the following information: ** Inception date ** Activity, including the repartition of commits per committer, the number of open issues, the mean time for fixing issues, etc. ** Documentation (reference material, tutorials, how-to guides, and explanations) Community, if any Support Tento tip: Be as careful in choosing a GitHub Action as in choosing any other dependency. Poznejte své činy Stejně jako předchozí tip, tento pochází z obecnějšího – mluvím z zkušeností.Byl jsem vyvíjet pracovní postup pro balení aplikace Java.Byl jsem silně používat pracovní postup, a práce musela stáhnout závislosti při každém spuštění. jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: actions/setup-java@v4 #1 with: distribution: temurin java-version: 21 - uses: actions/cache@v4 #2 with: path: ~/.m2/repository #3 key: ${{ platform }}-maven--${{ hashFiles('**/pom.xml') }} #4 restore-keys: | ${{ runner.os }}-maven- #4 Instalace JDK Nastavení vyrovnávací paměti. vyrovnávací paměť je obecná a může vyrovnávat soubory přes spuštění. Vytvořte místní úložiště Maven Klíč používá runner OS, který se nemění, a hash POM. Proto krok vytváří nový cache pokaždé, když se POM změní. Yet, reading the documentation, I realized I could achieve the same in a much more straightforward way: Akce má vestavěnou funkci pro vyrovnávání závislostí a obnovení závislostí. Používá nástrojový balíček / vyrovnávací paměť pod kapotou pro vyrovnávání závislostí, ale vyžaduje méně nastavení konfigurace. Podporované správce balíčků jsou gradle, maven a sbt. Formát použitého klíče vyrovnávací paměti je setup-java-${plattform }}-${ packageManager }}-${ fileHash }}, kde je hash založen na následujících souborech: Maven: ** / pom.xml Caching závislostí balíků Akce má vestavěnou funkci pro vyrovnávání a obnovení závislostí. Používá nástrojový kit / vyrovnávací paměť pod kapotou pro vyrovnávání závislostí, ale vyžaduje méně nastavení konfigurace. Podporované správce balíčků jsou gradle, maven a sbt. Formát použitého klíče vyrovnávací paměti je , kde je hash založen na následujících souborech: setup-java-${{ platform }}-${{ packageManager }}-${{ fileHash }} Maven: ** / pom.xml Caching závislostí balíků Vyměnil jsem tedy výše uvedený úryvek za následující: jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: actions/setup-java@v4 with: distribution: temurin java-version: 21 cache: maven #1 Tohle je to Tento tip: Strávit hodinu na dokumentaci vám může pomoci ušetřit lidské dny úsilí. Thoroughly read the documentation of actions. Vyzkoušejte svou verzi závislosti Tato sekce také bere obecné rady a aplikuje je na verzi GitHub workflows. najdete verze na nejméně dvou místech: na obrázku OCI a na verzi GitHub Actions. Možná jste si všimli, že v předchozích úryvcích. v okamžiku tohoto psaní poukazuje na Jak čas plyne, zobrazí se nejnovější verze s různými verzemi knihoven. Může to způsobit selhání při spuštění pracovního postupu nebo, co je ještě horší, změnit výstup způsobem, který si nevšimnete, dokud nebude příliš pozdě. (všechny dostupné obrázky runs-on: ubuntu-latest ubuntu-24.04 https://github.com/actions/runner-images Akce fungují jinak, protože poukazují na odkaz GitHub repo: buď tag nebo kompromisní SHA. Zatímco obraz OCI je v rukou GitHubu, akce je odpovědností jeho poskytovatele. To znamená, že každý s kompromisními právy může změnit obsah podkladové značky. Pin na kompromis. must jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@08c6903 #1 Pin na konkrétní kompromis 💡 Tip: Berte bezpečnost vážně a pin actions to a specific commit. Použijte shrnutí práce Každý z kroků pracovního postupu pravděpodobně produkuje spoustu protokolů. V pravidelném pracovním postupu může být celkové množství logových řádků poměrně obrovské. Některé z nich mohou být užitečné, některé z nich nemusí být, ale protože existuje pouze standardní výstup a standardní chyba, vše končí na stejném místě. , počet testů spuštěných nebo procento pokrytí kódu, v případě, že tyto údaje neposíláte jinde. GitHub usnadňuje přidání dat, které chcete do shrnutí práce. Jde o g. Můžete použít souhrny úkolů k zobrazení a seskupení jedinečného obsahu, například souhrny výsledků testů, takže někdo, kdo si prohlíží výsledek běhu pracovního postupu, nemusí přejít do protokolů, aby viděl důležité informace související s během, například selhání. Shrnutí pracovních míst podporuje GitHub příchuť Markdown, a můžete přidat svůj obsah Markdown na krok do prostředí souboru GITHUB_STEP_SUMMARY. Přidání shrnutí práce Můžete použít souhrny úkolů k zobrazení a seskupení jedinečného obsahu, například souhrny výsledků testů, takže někdo, kdo si prohlíží výsledek běhu pracovního postupu, nemusí přejít do protokolů, aby viděl důležité informace související s během, například selhání. Shrnutí práce podporuje GitHub příchuť Markdown, a můžete přidat svůj obsah Markdown pro krok k Environmentální archiv Je jedinečný pro každý krok v práci. GITHUB_STEP_SUMMARY GITHUB_STEP_SUMMARY - - - Přidání shrnutí práce Here's a Pro více informací o Apache Arrow: vzorek - name: Show inputs run: | echo "upload_artifacts: ${{ inputs.upload_artifacts }}" >> $GITHUB_STEP_SUMMARY echo "schedule: ${{ github.event.schedule }}" >> $GITHUB_STEP_SUMMARY echo "ref: ${{ github.ref }}" >> $GITHUB_STEP_SUMMARY Tyto Je to: Výsledek Tento tip: Zlepšení zkušeností vývojářů. Use GitHub job summary Pochopení životního cyklu pracovních postupů Pracovní postupy spouštějí kroky postupně. Neúspěšný krok zruší všechny zbývající kroky a pracovní postup skončí v Ve výše uvedeném příkladu to znamená, že nebudeme vůbec dostávat žádné shrnutí testů, pokud některý z následujících kroků selže. Podmínkou je Failure if Následující funkce kontroly stavu můžete použít jako výrazy v případě podmínek. Předvolená kontrola stavu úspěchu() se použije, pokud nezahrnete jednu z těchto funkcí. Funkce Status Check Následující funkce kontroly stavu můžete použít jako výrazy v případě podmínek. Předvolená kontrola stavu úspěchu() se použije, pokud nezahrnete jednu z těchto funkcí. Funkce Status Check GitHub používá Výchozí, ale možnosti zahrnují , , , a . success() always() cancelled() failure() - name: Show inputs if: ${{ always() }} #1 run: | echo "upload_artifacts: ${{ inputs.upload_artifacts }}" >> $GITHUB_STEP_SUMMARY echo "schedule: ${{ github.event.schedule }}" >> $GITHUB_STEP_SUMMARY echo "ref: ${{ github.ref }}" >> $GITHUB_STEP_SUMMARY Vždy provádějte krok, bez ohledu na to, zda předchozí kroky byly úspěšné nebo ne Představte si následující sekvenci: - name: Step that may fail run: whatever - name: Execute unit tests run: ./mvnw -B test #1 - name: Test Summary if: ${{ always() }} uses: test-summary/action@31493c7 #2 Spuštěné jednotkové testy také generují zprávy JUnit Použijte generované zprávy JUnit k napsání shrnutí kroků Pokud první krok selže, shrnutí se provede bez ohledu na to, zda byly testy spuštěny. Kdyby ne, selhalo by. Abychom tomu zabránili, musíme podmínku dále zdokonalit tak, aby se shrnutí provádělo pouze v případě, že testovací krok jednotky. - name: Step that may fail run: whatever - name: Execute unit tests id: test #1 run: ./mvnw -B test - name: Test Summary if: ${{ always() && steps.test.conclusion == 'success'}} #2 uses: test-summary/action@31493c7 Nastavení ID kroku Spustit pouze v případě, že testovací krok běží úspěšně Je to jen jednoduchý příklad, ale nabízí zajímavé možnosti. Tento tip: Využijte ji ve svůj prospěch. Know workflows' lifecycle Testování lokálně Mnoho organizací prosazuje přísná pravidla GitHub. Nejrozšířenější je, že nemůžete tlačit na : Každý kompromis musí projít žádostí o stažení. I když má smysl pro zavedené projekty, brání tomu, aby se projekty začaly rychle iterovat a zároveň si zachovaly historii kompromisů. master Přichází návrh zákona: „Myslet globálně, jednat lokálně“ Proveďte své akce GitHub lokálně! Proč byste to chtěli udělat? Dva důvody: - Rather than having to commit/push every time you want to test out the changes you are making to your files (or for any changes to embedded GitHub actions), you can use act to run the actions locally. The environment variables and filesystem are all configured to match what GitHub provides. Fast Feedback .github/workflows/ - I love make. However, I also hate repeating myself. With , you can use the GitHub Actions defined in your to replace your ! Local Task Runner act .github/workflows/ Makefile Úvod do akcí „Myslet globálně, jednat lokálně“ Proveďte své akce GitHub lokálně! Proč byste to chtěli udělat? Dva důvody: Rychlá zpětná vazba - Místo toho, abyste museli provádět / tlačit pokaždé, když chcete otestovat změny, které provádíte ve vašich souborech .github / workflows / (nebo pro jakékoli změny v vložených akcích GitHub), můžete použít akci k spuštění akcí lokálně. Local Task Runner - miluji dělat. Nicméně, taky se nenávidím opakovat. S akcí, můžete použít akce GitHub definované ve vašem .github/workflows/ nahradit váš Makefile! - - - Úvod do act má integraci GitHub CLI, která spouští pracovní postup podle správné události. act gh act push Zde je výstup, když byly obrázky a akce již staženy: INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' [workflow.yml/test] ⭐ Run Set up job [workflow.yml/test] 🚀 Start image=catthehacker/ubuntu:act-22.04 [workflow.yml/test] 🐳 docker pull image=catthehacker/ubuntu:act-22.04 platform= username= forcePull=true [workflow.yml/test] 🐳 docker create image=catthehacker/ubuntu:act-22.04 platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" [workflow.yml/test] 🐳 docker run image=catthehacker/ubuntu:act-22.04 platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" [workflow.yml/test] 🐳 docker exec cmd=[node --no-warnings -e console.log(process.execPath)] user= workdir= [workflow.yml/test] ✅ Success - Set up job [workflow.yml/test] ☁ git clone 'https://github.com/actions/setup-java' # ref=v4 [workflow.yml/test] ⭐ Run Main actions/checkout@v4 [workflow.yml/test] 🐳 docker cp src=/Users/nico/projects/act-sample/. dst=/Users/nico/projects/act-sample [workflow.yml/test] ✅ Success - Main actions/checkout@v4 [9.211777902s] [workflow.yml/test] ⭐ Run Main Setup JDK [workflow.yml/test] 🐳 docker cp src=/home/nico/.cache/act/actions-setup-java@v4/ dst=/var/run/act/actions/actions-setup-java@v4/ [workflow.yml/test] 🐳 docker exec cmd=[/opt/acttoolcache/node/18.20.8/x64/bin/node /var/run/act/actions/actions-setup-java@v4/dist/setup/index.js] user= workdir= [workflow.yml/test] ❓ ::group::Installed distributions | Resolved Java 21.0.8+9.0.LTS from tool-cache | Setting Java 21.0.8+9.0.LTS as the default | Creating toolchains.xml for JDK version 21 from temurin | Writing to /root/.m2/toolchains.xml | | Java configuration: | Distribution: temurin | Version: 21.0.8+9.0.LTS | Path: /opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/21.0.8-9.0.LTS/x64 | [workflow.yml/test] ❓ ::endgroup:: [workflow.yml/test] ❓ add-matcher /run/act/actions/actions-setup-java@v4/.github/java.json | Creating settings.xml with server-id: github | Writing to /root/.m2/settings.xml [workflow.yml/test] ⚙ *** | Cache Size: ~50 MB (52710428 B) | [command]/usr/bin/tar -xf /tmp/c8ef4803-85c1-4867-ac2d-442dbce79755/cache.tzst -P -C /Users/nico/projects/act-sample --use-compress-program unzstd | Cache restored successfully | Cache restored from key: setup-java-linux-x64-maven-ef0e54e9035c18b60db7ea0af5e2f0c4cc5445dd6a2a2a672b91e14f14e7e4c2 [workflow.yml/test] ✅ Success - Main Setup JDK [2.514565962s] [workflow.yml/test] ⚙ ::set-env:: JAVA_HOME=/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/21.0.8-9.0.LTS/x64 [workflow.yml/test] ⚙ ::set-env:: JAVA_HOME_21_X64=/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/21.0.8-9.0.LTS/x64 [workflow.yml/test] ⚙ ::set-output:: distribution=Temurin-Hotspot [workflow.yml/test] ⚙ ::set-output:: path=/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/21.0.8-9.0.LTS/x64 [workflow.yml/test] ⚙ ::set-output:: version=21.0.8+9.0.LTS [workflow.yml/test] ⚙ ::set-output:: cache-hit=false [workflow.yml/test] ⚙ ::add-path:: /opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/21.0.8-9.0.LTS/x64/bin [workflow.yml/test] ⭐ Run Main Run "fast" tests [workflow.yml/test] 🐳 docker exec cmd=[bash -e /var/run/act/workflow/2] user= workdir= | [INFO] Scanning for projects... | [INFO] | [INFO] ---- ----- | [INFO] Building act-sample 1.0-SNAPSHOT | [INFO] from pom.xml | [INFO] ------------------------[ jar ]------------------------- | [INFO] | [INFO] --- resources:3.3.1:resources (default-resources) @ act-sample --- | [INFO] Copying 1 resource from src/main/resources to target/classes | [INFO] | [INFO] --- compiler:3.14.0:compile (default-compile) @ act-sample --- | [INFO] Recompiling the module because of changed source code. | [INFO] Compiling 5 source files with javac [debug target 21] to target/classes | [INFO] | [INFO] --- resources:3.3.1:testResources (default-testResources) @ act-sample --- | [INFO] Copying 2 resources from src/test/resources to target/test-classes | [INFO] | [INFO] --- compiler:3.14.0:testCompile (default-testCompile) @ act-sample --- | [INFO] Recompiling the module because of changed dependency. | [INFO] Compiling 1 source file with javac [debug target 21] to target/test-classes | [INFO] | [INFO] --- surefire:3.2.5:test (default-test) @ act-sample --- | [INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider | [INFO] | [INFO] ------------------------------------------ | [INFO] T E S T S | [INFO] ------------------------------------------ | [INFO] Running ch.frankel.blog.ActSampleTest | [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.120 s -- in ch.frankel.blog.ActSampleTest | [INFO] | [INFO] Results: | [INFO] | [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 | [INFO] | [INFO] ------------------------------------------------------ | [INFO] BUILD SUCCESS | [INFO] ------------------------------------------------------ | [INFO] Total time: 3.318 s | [INFO] Finished at: 2025-08-22T10:26:29Z | [INFO] ------------------------------------------------------ [workflow.yml/test] ✅ Success - Main Run "fast" tests [20.920776212s] [workflow.yml/test] ⭐ Run Post Setup JDK [workflow.yml/test] 🐳 docker exec cmd=[/opt/acttoolcache/node/18.20.8/x64/bin/node /var/run/act/actions/actions-setup-java@v4/dist/cleanup/index.js] user= workdir= | [command]/usr/bin/tar --posix -cf cache.tzst --exclude cache.tzst -P -C /Users/nico/projects/act-sample --files-from manifest.txt --use-compress-program zstdmt | Cache Size: ~50 MB (52701753 B) | Cache saved successfully | Cache saved with the key: setup-java-Linux-x64-maven-ef0e54e9035c18b60db7ea0af5e2f0c4cc5445dd6a2a2a672b91e14f14e7e4c2 [workflow.yml/test] ✅ Success - Post Setup JDK [1.01412383s] [workflow.yml/test] ⭐ Run Complete job [workflow.yml/test] Cleaning up container for job test [workflow.yml/test] ✅ Success - Complete job [workflow.yml/test] 🏁 Job succeeded Můžu napsat pár článků na Nechám vás přečíst si dokumentaci. act Tento tip: Zkrácení času vašeho feedback cyklu. Test your workflows locally Summary Používejte správnou sémantiku, rozlišujte mezi pracovními postupy a akcemi. Upřednostňuji akce GitHub před příkazy ad-hoc. Buďte při výběru akce GitHub stejně opatrní jako při výběru jakékoliv jiné závislosti. Pečlivě si přečtěte dokumentaci každé akce, kterou používáte. Pin akce na konkrétní kompromis. Použijte souhrn práce GitHub ke zlepšení zkušeností vývojářů. Znáte životní cyklus pracovních postupů. Vyzkoušejte své pracovní postupy lokálně. To go further: O pracovních postupech GitHub akce GitHub Akční trh Runner obrázky Přidání shrnutí práce Funkce kontroly stavu Úvod do akcí