Практическо ръководство за изграждане на по-умни работни потоци на GitHub

Имам доста дълъг опит с работните потоци на GitHub, но не до точката, в която мога да твърдя, че съм експерт. Какво представляват GitHub Workflows? Работен поток е конфигурируем автоматизиран процес, който ще изпълнява една или повече задачи. Работните потоци се определят от YAML файл, който се вписва във вашия регистър и ще се изпълнява, когато се задейства от събитие във вашия регистър, или те могат да бъдат задействани ръчно или по определен график. Работните потоци са дефинирани в директорията .github/workflows в репозиторията. Репозиторията може да има множество работни потоци, всеки от които може да изпълнява различен набор от задачи, като например: Изграждане и тестване на искания за изтегляне Разполагане на приложението ви всеки път, когато се създава версия Adding a label whenever a new issue is opened За работните потоци Работен поток е конфигурируем автоматизиран процес, който ще изпълнява една или повече задачи. Работните потоци се определят от YAML файл, който се вписва във вашия регистър и ще се изпълнява, когато се задейства от събитие във вашия регистър, или те могат да бъдат задействани ръчно или по определен график. Работните потоци са дефинирани в директорията .github/workflows в репозиторията. Репозиторията може да има множество работни потоци, всеки от които може да изпълнява различен набор от задачи, като например: Изграждане и тестване на искания за изтегляне Разполагане на приложението ви всеки път, когато се създава версия Добавяне на етикет всеки път, когато се отвори нова тема За работните потоци По този начин работният поток е сравним с работата на Jenkins, реализирана в YAML вместо XML. , за разлика от традиционната конфигурация на работата на Дженкинс. Не изглежда много, но позволява използването на подходи за управление на изходния код, включително версиониране и връщане назад.Преди години работех за клиент, чийто екип на DevOps прилага подход, базиран на кукла, за да възстанови работата на Дженкинс, така че конфигурацията на куклата да може да се съхранява в Git. Това беше огромно усилие! stored inside the code repository Имайте предвид, че GitHub беше доста късно за партито.Преди да изпълни работните потоци, използвах услуга на трета страна, наречена Превключих главно, защото Травис стана платен и вторично, защото работните потоци са вродена част от GitHub. Травис Ти Този тип: Те се наричат Действията на GitHub са напълно различни. Use the correct semantics Работни потоци на GitHub Дейности на GitHub Работните потоци на GitHub се състоят от които са съставени от Стъпки за препращане няколко параметъра, включително име. Работни места стъпки бягане jobs: metrics: runs-on: my-image #1 steps: - name: Install dependencies via Poetry #2 run: poetry install #3 OCI изображение, върху което работи работният поток Стъпка на име Командване стъпка GitHub Actions са многократно използваеми компоненти, които предлагат алтернативи на повтарянето на една и съща команда отново и отново. Действие е предварително дефиниран набор от задачи или код, който може да се използва повторно, който изпълнява конкретни задачи в работния поток, като намалява количеството повтарящ се код, който пишете в файловете на работния поток. Изтегляне на вашия Git repository от GitHub Setting up the correct toolchain for your build environment Setting up authentication for your cloud provider Можете да напишете свои собствени действия или да намерите действия, които да използвате в работните си потоци в GitHub Marketplace. Например, вместо да изпълнявате git checkout, можете да използвате действието checkout. GitHub действие Действие е предварително дефиниран набор от задачи или код, който може да се използва повторно, който изпълнява конкретни задачи в работния поток, като намалява количеството повтарящ се код, който пишете в файловете на работния поток. Изтегляне на вашия Git repository от GitHub Настройване на правилната верига от инструменти за вашата среда за изграждане Настройване на удостоверяване за вашия облачен доставчик Можете да напишете свои собствени действия или да намерите действия, които да използвате в работните си потоци в Например, вместо да изпълнявате Можете да използвате . GitHub пазар git checkout Checkout действие GitHub действие jobs: metrics: runs-on: my-image steps: - uses: actions/checkout@v5 #1 with: #2 fetch-depth: 0 submodules: recursive Създаване на GitHub Action Параметри на действие Аз съм голям фен на не изобретяването на колелото. GitHub Actions играе голяма роля в това. Този тип: Когато е възможно. Prefer GitHub Actions over ad-hoc commands Изборът на правилното действие Гостите на GitHub Marketplace Действията са изброени по категории. Можете да филтрирате по тип създател и да ги сортирате по популярност. Много действия При избора на действие, трябва да упражнявате същата грижа, както при въвеждането на всяка друга зависимост. Ето няколко критерия, които ще ви помогнат: 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 Този тип: Be as careful in choosing a GitHub Action as in choosing any other dependency. Познайте действията си Както и предишният съвет, този произхожда от по-общ – говоря от опит.Разработвах работен поток за опаковане на приложението на Java.Използвах работния поток силно и работата трябваше да изтегля зависимостите при всяко изпълнение. 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 Инсталиране на JDK Настройване на кеш. кешът е общ и може да кешира файлове по време на изпълнение. Поддръжка на локалния Maven repository Ключът използва операционната система на бегача, която не се променя, и хаша на POM. Следователно, стъпката създава нов кеш всеки път, когато POM се променя. И все пак, като прочетох документацията, осъзнах, че мога да постигна същото по много по-прост начин: Действието има вградена функционалност за кеширане и възстановяване на зависимостите. Той използва toolkit/cache под капака за кеширане на зависимостите, но изисква по-малко настройки за конфигуриране. Поддържаните мениджъри на пакети са gradle, maven и sbt. Форматът на използвания кеш ключ е setup-java-${{ платформа }}-${ packageManager }}-${ fileHash }}, където хешът се основава на следните файлове: Съдържание: * / pom.xml • Зависимост от пакети Действието има вградена функционалност за кеширане и възстановяване на зависимостите. Той използва toolkit/cache под капака за кеширане на зависимостите, но изисква по-малко конфигурационни настройки. Поддържаните мениджъри на пакети са gradle, maven и sbt. Форматът на използвания кеш ключ е , където хешът се основава на следните файлове: setup-java-${{ platform }}-${{ packageManager }}-${{ fileHash }} Съдържание: * / pom.xml • Зависимост от пакети Замених горепосочения откъс със следното: 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 Това е Този тип: Прекарването на един час на документацията може да ви помогне да спестите дни от усилия. Thoroughly read the documentation of actions. Пин вашата версия на зависимостта Този раздел също така взема общи съвети и ги прилага към версията на работните потоци на GitHub. Може би сте забелязали, че в предишните откъси.В момента на това писане, той посочва, че С течение на времето, той ще посочи най-новата версия, с различни версии на библиотеки. Това може да доведе до неизправност по време на изпълнението на работния поток, или по-лошо, промяна на изхода по начини, които няма да забележите, докато не е твърде късно. [Всички налични снимки] runs-on: ubuntu-latest ubuntu-24.04 https://github.com/actions/runner-images Версионирането на действията работи по различен начин, тъй като те сочат към препратката на GitHub: или етикет, или етикет за компромис.Докато OCI изображението е в ръцете на GitHub, действието е отговорност на неговия доставчик.Това означава, че всеки с права за компромис може да промени съдържанието на основния етикет. Пин към компромис. must jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@08c6903 #1 Пин към конкретен компромис 💡 Съвет: Вземете сигурността сериозно и pin actions to a specific commit. Използвайте резюмето на работата Всяка от стъпките на вашия работен поток вероятно произвежда много дневници. В редовен работен поток общият брой линии на дневника може да бъде доста огромен. Някои от тях може да са полезни, някои от тях може да не са, но тъй като има само стандартен изход и стандартна грешка, всичко завършва на едно и също място. , броят на тестовете, които се изпълняват или процента на покритието на кода, в случай, че не изпращате тези данни някъде другаде. Е. от гр. Можете да използвате резюмета на задачи, за да показвате и групирате уникално съдържание, като например резюмета на резултатите от теста, така че някой, който преглежда резултата от изпълнение на работния поток, да не трябва да влиза в дневниците, за да вижда важна информация, свързана с изпълнението, като например неуспехи. Работните резюмета поддържат GitHub подправени Markdown, и можете да добавите съдържанието си Markdown за една стъпка към GITHUB_STEP_SUMMARY среда файл. Добавяне на резюме на работата Можете да използвате резюмета на задачи, за да показвате и групирате уникално съдържание, като например резюмета на резултатите от теста, така че някой, който преглежда резултата от изпълнение на работния поток, да не трябва да влиза в дневниците, за да вижда важна информация, свързана с изпълнението, като например неуспехи. Обобщенията за работа поддържат GitHub подправени Markdown, и можете да добавите съдържанието си Markdown за една стъпка към Архив на околната среда. Той е уникален за всяка стъпка в работата. GITHUB_STEP_SUMMARY GITHUB_STEP_SUMMARY Добавяне на резюме на работата Ето я A от Apache Arrow: Образецът - 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 на Това е: Резултат Този тип: Повишаване на опита на разработчиците. Use GitHub job summary Разбиране на жизнения цикъл на работните потоци Работните потоци изпълняват стъпки последователно. Една неуспешна стъпка отменя всички останали стъпки и работният поток завършва с В примера по-горе това означава, че няма да получим никакво резюме на теста, ако някоя от следващите стъпки се провали. на условие. Failure if Можете да използвате следните функции за проверка на състоянието като изрази в ако условни. По подразбиране проверка на състоянието на успеха() се прилага, освен ако не включите някоя от тези функции. Функции за проверка на състоянието Можете да използвате следните функции за проверка на състоянието като изрази в Проверка на състоянието по подразбиране се прилага, освен ако не включите някоя от тези функции. if success() Функции за проверка на състоянието GitHub използва по подразбиране, но опциите включват , и . 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 Винаги изпълнявайте стъпката, независимо дали предишните стъпки са били успешни или не Сега си представете следната последователност: - 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 Извършването на тестове на единици също генерира доклади JUnit Използвайте генерираните отчети на JUnit, за да напишете обобщение на стъпките Ако първата стъпка се провали, обобщението се изпълнява независимо от това дали са били изпълнени тестовете. Ако не са били изпълнени, ще се провали. За да избегнем това, трябва да усъвършенстваме условието по-нататък, така че обобщената стъпка да се изпълнява само ако е изпълнена единичната стъпка за изпитване. - 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 Задайте ID на стъпката Изпълнявайте само ако тестовият етап завърши успешно Това е само един прост пример, но предлага интересни възможности. Този тип: Използвайте го в своя полза. Know workflows' lifecycle Тест на местно ниво Много организации прилагат строги правила на GitHub. Най-широко разпространеният е, че не можете да натиснете : Всеки компромис трябва да премине през искане за изтегляне.Докато има смисъл за установени проекти, той предотвратява стартирането на проекти от бързо повтаряне, като същевременно запазва историята на компромиса. master Идва законопроектът: „Мисли глобално, действай локално“ Изпълнете действията си на GitHub локално! Защо бихте искали да направите това? - 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/ Локален изпълнител на задачи - Обичам да правя. Въпреки това, аз също мразя да се повтарям. С действие, можете да използвате действията на GitHub, определени във вашия .github/workflows/ за да замените вашия Makefile! - Въведение в акта „Мисли глобално, действай локално“ Изпълнете действията си на GitHub локално! Защо бихте искали да направите това? Бърза обратна връзка - Вместо да се налага да се ангажирате / натискате всеки път, когато искате да тествате промените, които правите на вашите .github / workflows / файлове (или за всякакви промени в вградените действия на GitHub), можете да използвате действието, за да изпълните действията локално. Локален изпълнител на задачи - Обичам да правя. Въпреки това, аз също мразя да се повтарям. С действие, можете да използвате действията на GitHub, определени във вашия .github/workflows/ за да замените вашия Makefile! - Въведение в акта има GitHub CLI интеграция, която задейства работния поток според правилното събитие. act gh act push Ето изхода, когато вече са изтеглени изображения и действия: 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 Бих могъл да напиша няколко статии за Ще ви оставя да прочетете документацията. act Този тип: Намаляване на времето за цикъл на обратна връзка. Test your workflows locally Резюме Използвайте правилната семантика, диференцирайте работните потоци и действията. Предпочитам GitHub Actions пред ad-hoc команди. Бъдете толкова внимателни при избора на действие на GitHub, колкото при избора на всяка друга зависимост. Прочетете внимателно документацията за всяко действие, което използвате. Пин действия към конкретен компромис. Използвайте GitHub резюме на работата, за да подобрите опита на разработчиците. Познайте жизнения цикъл на работните потоци. Тествайте работните си потоци на местно ниво. To go further: За работните потоци GitHub действие GitHub Marketplace за действие Изображения на Runner Добавяне на резюме на работата Проверка на функциите Въведение в акта