Een praktische gids voor het bouwen van slimmere GitHub-werkstromen

Ik heb een vrij lange ervaring met GitHub workflows, maar niet tot het punt waar ik kan beweren dat ik een expert ben. Wat zijn GitHub workflows? Een workflow is een configurerbaar geautomatiseerd proces dat één of meer taken uitvoert. workflows worden gedefinieerd door een YAML-bestand dat wordt ingecheckt in uw repository en worden uitgevoerd wanneer deze worden geactiveerd door een gebeurtenis in uw repository, of ze kunnen handmatig worden geactiveerd of op een gedefinieerd schema. Workflows worden gedefinieerd in de directory .github/workflows in een repository. Een repository kan meerdere workflows hebben, die elk een andere reeks taken kunnen uitvoeren, zoals: Bouw en testen pull verzoeken De implementatie van uw applicatie elke keer dat een release wordt gemaakt Een label toevoegen wanneer een nieuw issue wordt geopend - Over workflows Een workflow is een configurerbaar geautomatiseerd proces dat één of meer taken uitvoert. workflows worden gedefinieerd door een YAML-bestand dat wordt ingecheckt in uw repository en worden uitgevoerd wanneer deze worden geactiveerd door een gebeurtenis in uw repository, of ze kunnen handmatig worden geactiveerd of op een gedefinieerd schema. De workflows worden gedefinieerd in de Een repository kan meerdere workflows hebben, die elk een andere reeks taken kunnen uitvoeren, zoals: .github/workflows Bouw en testen pull verzoeken De implementatie van uw applicatie elke keer dat een release wordt gemaakt Een label toevoegen wanneer een nieuw issue wordt geopend - Over workflows Als zodanig is een workflow vergelijkbaar met een Jenkins-job, geïmplementeerd in YAML in plaats van XML. , in tegenstelling tot een erfelijke Jenkins-jobconfiguratie. Het ziet er niet veel uit, maar het maakt het mogelijk om broncodebeheerbenaderingen te gebruiken, waaronder versieën en terugrollen.Jaren geleden werkte ik voor een klant wiens DevOps-team een Puppet-gebaseerde benadering heeft geïmplementeerd om Jenkins-jobs te reconstrueren zodat de Puppet-configuratie in Git kon worden opgeslagen. stored inside the code repository Merk op dat GitHub vrij laat was voor de partij.Voordat het workflows implementeerde, gebruikte ik een dienst van derden genaamd Ik schakelde voornamelijk over omdat Travis betaald werd en secundair omdat workflows natief deel uitmaken van GitHub. door Travis CI Deze tip: : ze worden genoemd GitHub-acties zijn totaal anders. Use the correct semantics GitHub werkstromen GitHub acties GitHub workflows bestaan uit die zelf uit de Stappen van referentie Commando's en een paar optionele parameters, waaronder een naam. banen Stappen Rennen jobs: metrics: runs-on: my-image #1 steps: - name: Install dependencies via Poetry #2 run: poetry install #3 OCI-afbeelding waarop de workflow wordt uitgevoerd Stap naam Stap commando GitHub-acties zijn herbruikbare componenten die alternatieven bieden om hetzelfde commando steeds opnieuw te herhalen. Een actie is een vooraf gedefinieerde, herbruikbare reeks taken of code die specifieke taken uitvoert binnen een werkstroom, waardoor de hoeveelheid herhaalde code die u in uw werkstroombestanden schrijft, wordt verminderd. Pulling your Git repository from GitHub Het opzetten van de juiste toolchain voor uw bouwomgeving Authenticatie instellen voor uw cloudprovider U kunt uw eigen acties schrijven, of u kunt acties vinden om te gebruiken in uw workflows in de GitHub Marketplace. GitHub actie Een actie is een vooraf gedefinieerde, herbruikbare reeks taken of code die specifieke taken uitvoert binnen een werkstroom, waardoor de hoeveelheid herhaalde code die u in uw werkstroombestanden schrijft, wordt verminderd. Uw Git-repository verwijderen van GitHub Het opzetten van de juiste toolchain voor uw bouwomgeving Authenticatie instellen voor uw cloudprovider U kunt uw eigen acties schrijven, of u kunt acties vinden om te gebruiken in uw workflows in de GitHub Marketplace. GitHub actie jobs: metrics: runs-on: my-image steps: - uses: actions/checkout@v5 #1 with: #2 fetch-depth: 0 submodules: recursive Verwijzing naar een GitHub-actie Actie Parameters Ik ben een grote fan van het niet opnieuw uitvinden van het wiel. GitHub Actions spelen daarin een grote rol. Deze tip: Wanneer mogelijk Prefer GitHub Actions over ad-hoc commands De juiste actie kiezen De GitHub Marketplace hosts Acties worden weergegeven op categorieën. U kunt filteren op creator type en sorteren op populariteit. Veel acties Bij het kiezen van een actie, moet u dezelfde zorg uitoefenen als bij het brengen in een andere verslaving. 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 Deze tip: Be as careful in choosing a GitHub Action as in choosing any other dependency. Ken je acties Net als de vorige tip komt deze van een meer algemene - ik spreek uit ervaring. ik ontwikkelde een workflow om een Java-toepassing te verpakken. ik gebruikte de workflow hard, en de taak moest de afhankelijkheden bij elke run downloaden. 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 Installeer een JDK Stel een cache in. De cache is generiek en kan bestanden over runs cachen. Cacheer het lokale Maven-repository Cache-afhankelijkheden De sleutel gebruikt het runner-OS, dat niet verandert, en de hash van de POM. Toch besefte ik, na het lezen van de documentatie, dat ik hetzelfde op een veel eenvoudiger manier kon bereiken: De actie heeft een ingebouwde functionaliteit voor het cachen en herstellen van afhankelijkheden. Het maakt gebruik van een toolkit/cache onder hood voor het cachen van afhankelijkheden, maar vereist minder configuratieinstellingen. Ondersteunde pakketbeheerders zijn gradle, maven en sbt. Het formaat van de gebruikte cache sleutel is setup-java-${platform }}-${ packageManager }}-${ fileHash }}, waarbij de hash is gebaseerd op de volgende bestanden: Maven: **/pom.xml voor Mac Caching pakket afhankelijkheden De actie heeft een ingebouwde functionaliteit voor het cachen en herstellen van afhankelijkheden. Het maakt gebruik van een toolkit/cache onder hood voor het cachen van afhankelijkheden, maar vereist minder configuratie-instellingen. Ondersteunde pakketbeheerders zijn gradle, maven en sbt. waar de hash is gebaseerd op de volgende bestanden: setup-java-${{ platform }}-${{ packageManager }}-${{ fileHash }} Maven: **/pom.xml voor Mac Caching pakket afhankelijkheden Ik heb het bovenstaande snippet vervangen door het volgende: 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 Dit is het Deze tip: Het besteden van een uur aan de documentatie kan u helpen dagen van inspanning te besparen. Thoroughly read the documentation of actions. Pin uw versie van afhankelijkheid Deze sectie neemt ook algemene adviezen en past deze toe op de versie van GitHub workflows. Misschien heb je opgemerkt dat de in de vorige snippets. op het moment van dit schrijven, wijst het op Naarmate de tijd verstrijkt, wijst het op de nieuwste versie, met versies van verschillende bibliotheken. Het kan een storing veroorzaken tijdens de uitvoering van de workflow, of erger nog, de output wijzigen op manieren die u niet zou opmerken totdat het te laat is. [Alle beschikbare afbeeldingen zijn beschikbaar] runs-on: ubuntu-latest ubuntu-24.04 https://github.com/actions/runner-images De versie van Actions werkt anders, omdat ze wijzen op de verwijzing van een GitHub-repo: een tag of een commit SHA. Terwijl de OCI-afbeelding in de handen van GitHub is, is de actie de verantwoordelijkheid van de provider. Pin naar een commit. must jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@08c6903 #1 Pin naar een specifieke opdracht 💡 Tip: Neem veiligheid serieus en pin actions to a specific commit. Gebruik de samenvatting van de baan Elk van uw werkstroom stappen waarschijnlijk produceert veel logs. In een reguliere werkstroom, de totale hoeveelheid log lijnen kan heel groot zijn. Sommige van hen kunnen nuttig zijn, sommige van hen misschien niet, maar omdat er slechts een standaard output en standaard fout, alles eindigt op dezelfde plaats. , het aantal testen dat wordt uitgevoerd of het percentage code-dekking, in het geval dat u deze gegevens niet ergens anders verzendt. GitHub maakt het eenvoudig om de gegevens die u wilt toe te voegen aan de samenvatting van de taak. Het e.g. U kunt functieverzamelingen gebruiken om unieke inhoud, zoals testresultatenverzamelingen, weer te geven en te groeperen, zodat iemand die het resultaat van een workflow uitvoert, niet naar de logboeken hoeft te gaan om belangrijke informatie over de uitvoering, zoals mislukkingen, te zien. Job samenvattingen ondersteunen GitHub-gearomatiseerde Markdown, en u kunt uw Markdown-inhoud voor een stap toevoegen aan het GITHUB_STEP_SUMMARY-omgevingbestand. Een samenvatting van de baan toevoegen U kunt functieverzamelingen gebruiken om unieke inhoud, zoals testresultatenverzamelingen, weer te geven en te groeperen, zodat iemand die het resultaat van een workflow uitvoert, niet naar de logboeken hoeft te gaan om belangrijke informatie over de uitvoering, zoals mislukkingen, te zien. Job samenvattingen ondersteunen GitHub smaakvol Markdown, en u kunt uw Markdown-inhoud voor een stap toevoegen aan de Het milieu bestand. Het is uniek voor elke stap in een baan. GITHUB_STEP_SUMMARY GITHUB_STEP_SUMMARY - - - Een samenvatting van de baan toevoegen Hier is een Bij Apache Arrow: Samenstelling - 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 De is het: resultaat Deze tip: Om de ervaringen van de ontwikkelaar te verbeteren. Use GitHub job summary De levenscyclus van workflows begrijpen Een mislukte stap annuleert alle resterende stappen en de workflow eindigt in een In het bovenstaande voorbeeld betekent dit dat we helemaal geen testverzameling krijgen als een van de volgende stappen mislukt. De voorwaarde. Failure if U kunt de volgende statuscontrolefuncties gebruiken als uitdrukkingen in if conditionals. Een standaardstatuscontrole van succes() wordt toegepast, tenzij u een van deze functies opneemt. Status check functies U kunt de volgende statuscontrolefuncties gebruiken als uitdrukkingen in if conditionals. Een standaardstatuscontrole van succes() wordt toegepast, tenzij u een van deze functies opneemt. Status check functies GitHub gebruikt standaard, maar de opties omvatten - het en . 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 Altijd de stap uitvoeren, ongeacht of de vorige stappen succesvol waren of niet Stel je de volgende sequentie voor: - 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 Running unit tests genereert ook JUnit-rapporten Gebruik de gegenereerde JUnit-rapporten om een samenvatting van stappen te schrijven Als de eerste stap mislukt, wordt de samenvatting uitgevoerd ongeacht of de tests werden uitgevoerd. Als ze niet, zou het mislukken. Om dit te voorkomen, moeten we de voorwaarde verder te verfijnen, zodat de samenvatting stap alleen wordt uitgevoerd als de eenheid test stap deed. - 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 Stel de ID van de stap in Loop alleen als de teststap succesvol loopt Het is slechts een eenvoudig voorbeeld, maar het biedt interessante opties. Deze tip: En gebruik het in uw voordeel. Know workflows' lifecycle Test lokaal Veel organisaties handhaven strenge GitHub-regels. de meest voorkomende is dat je niet kunt duwen : elke opdracht moet een trekverzoek doorlopen.Hoewel het zinvol is voor gevestigde projecten, voorkomt het dat projecten snel worden herhaald terwijl de commitgeschiedenis wordt bewaard. master Komt het actieproject: “Denk wereldwijd, doe lokaal” Voer uw GitHub-acties lokaal uit! Waarom zou u dit willen doen? - 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/ Local Task Runner - Ik hou van maken. Echter, ik haat ook het herhalen van mezelf. Met actie, kunt u de GitHub Acties gedefinieerd in uw .github/workflows/ gebruiken om uw Makefile te vervangen! - Introductie tot de actie “Denk wereldwijd, doe lokaal” Voer uw GitHub-acties lokaal uit! Waarom zou u dit willen doen? Snelle feedback - In plaats van elke keer dat u de wijzigingen wilt testen die u aan uw .github/workflows/bestanden doet (of voor eventuele wijzigingen aan ingebedde GitHub-acties), kunt u actie gebruiken om de acties lokaal uit te voeren. de omgevingsvariabelen en het bestandssysteem zijn allemaal geconfigureerd om overeen te komen met wat GitHub biedt. Local Task Runner - Ik hou van maken. Echter, ik haat ook het herhalen van mezelf. Met actie, kunt u de GitHub Acties gedefinieerd in uw .github/workflows/ gebruiken om uw Makefile te vervangen! - - - Introductie naar act heeft een GitHub CLI-integratie die de workflow triggert volgens de juiste gebeurtenis. act gh act push Hier is de output wanneer afbeeldingen en acties al zijn gedownload: 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 Ik zou een paar berichten kunnen schrijven over Ik laat je de documentatie lezen. act Deze tip: Om de feedback cyclus te verkorten. Test your workflows locally Samenvatting Gebruik de juiste semantiek, onderscheid tussen workflows en acties. Voorkeur GitHub Actions boven ad-hoc commando's. Wees net zo voorzichtig bij het kiezen van een GitHub-actie als bij het kiezen van een andere afhankelijkheid. Lees zorgvuldig de documentatie van elke actie die u gebruikt. Pin acties naar een specifieke commit. Gebruik GitHub Job Summary om de ontwikkelaarservaring te verbeteren. Ken de levenscyclus van workflows. Test uw workflows lokaal. To go further: Over workflows GitHub actie GitHub actie marktplaats Runner beelden Een samenvatting van de baan toevoegen Status Check functies Introductie tot actie