よりスマートなGitHubワークフローを構築するための実践的なガイド

私はGitHubのワークフローについてかなり長い経験を持っていますが、私が専門家であると主張できるほどではありませんが、私は最近新しいワークフローを開発し、この投稿を書くように促しました。 GitHubのワークフローとは? ワークフローは、リポジトリにチェックインされた YAML ファイルによって定義され、リポジトリ内のイベントによって引き起こされた場合に実行されるか、手動でまたは定義されたスケジュールで引き起こすことができます。 ワークフローは、リポジトリ内の .github/workflows ディレクトリで定義されます. A repository can have multiple workflows, each of which can perform a different set of tasks, such as: 構築とテスト トラック リクエスト リリースが作成されるたびにアプリケーションを展開する 新しいエピソードが開くたびにラベルを追加する ■ワークフローについて ワークフローは、リポジトリにチェックインされた YAML ファイルによって定義され、リポジトリ内のイベントによって引き起こされた場合に実行されるか、手動でまたは定義されたスケジュールで引き起こすことができます。 ワークフローは、The workflow is defined in the リポジトリのディレクトリ リポジトリには複数のワークフローが存在し、それぞれが以下のような異なるタスクセットを実行することができます。 .github/workflows 構築とテスト トラック リクエスト リリースが作成されるたびにアプリケーションを展開する 新しいエピソードが開くたびにラベルを追加する ■ワークフローについて したがって、ワークフローは、XML ではなく YAML で実装された Jenkins ワークフローと比較できますが、主な違いは、ワークフローの構成が それはあまり見えないが、バージョニングとリボリングを含むソースコード管理アプローチを使用することを可能にしている。何年も前に、DevOpsチームがJenkinsの仕事を再構築するためにPuppetベースのアプローチを実装したクライアントのために働いたので、Puppet configがGitに保存されることができた。 stored inside the code repository GitHub はパーティーにかなり遅れていたことに注意してください。ワークフローを実装する前に、私はサードパーティーのサービスを使用しました。 私は主にトラヴィスが支払われたため、そして次にワークフローがGitHubのネイティブな部分であるため、切り替えました。 トラヴィス CI ↓ タイプ: : They are called 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 イメージ ステップ名 STEPコマンド GitHub アクションは、同じコマンドを何度も繰り返すための代替を提供する再利用可能なコンポーネントです。 アクションは、ワークフロー内の特定のタスクを実行し、ワークフローファイルに書き込む繰り返しコードの量を減らす、事前に定義された、再利用可能なタスクまたはコードのセットです。 あなたのGitリポジトリをGitHubから引っ張る あなたのビルド環境のための正しいツールチェーンを設定する あなたのクラウドプロバイダーの認証の設定 自分のアクションを書くか、GitHub Marketplaceでワークフローで使用するアクションを見つけることができます. たとえば、Git Checkout を実行する代わりに、Checkout アクションを使用できます。 GitHub アクション アン 特定のタスクを実行する事前定義された、再利用可能な仕事またはコードのセットです。 ワークフロー ファイルに書き込む繰り返しコードの量を減らす アクションは、以下のようなタスクを実行できます。 action workflow あなたのGitリポジトリをGitHubから引っ張る あなたのビルド環境のための正しいツールチェーンを設定する あなたのクラウドプロバイダーの認証の設定 独自のアクションを書くか、ワークフローで使用するアクションを見つけることができます。 例えば、実行する代わりに、 , you can use the . 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. あなたの行動を知る 前回のヒントと同様に、このヒントはより一般的なものから生まれており、私は経験から話しています. I was developing a workflow to package a Java application. I was heavily using the workflow, and the job had to download the dependencies at every run. 私は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をインストール キャッシュを設定します. キャッシュは一般的で、ファイルをランダムでキャッシュできます。 Local Maven Repository をキャッシュする Cache dependencies. The key uses the runner OS, which does not change, and the POM's hash. Therefore, the step creates a new cache each time the POM changes. このキーは、POMが変更されるたびに新しいキャッシュを作成します。 しかし、ドキュメンタリーを読んで、私はもっと単純な方法で同じことを達成することができることに気付きました。 このアクションには、依存性のキャッシュおよび復元のための内蔵機能が備わっています。ツールキット/キャッシュはキャッシュ依存性をキャッシュするためにキャッシュするために使用されますが、構成設定が少なくなります。サポートされているパッケージマネージャーは gradle、maven、sbt です。使用されるキャッシュキーのフォーマットは setup-java-${{プラットフォーム }}-${ packageManager }}-${ fileHash }}で、ハッシュは次のファイルに基づいています: タグ: */pom.xml Caching Package Dependencies(パッケージの依存性) このアクションにはキャッシュおよび依存性を復元するための組み込みの機能があります. It uses toolkit/cache under hood for caching dependencies but requires less configuration settings. サポートされるパッケージマネージャーは gradle, maven and sbt. 使用されるキャッシュキーの形式は , where the hash is based on the following files. ハッシュは、以下のファイルに基づいています。 setup-java-${{ platform }}-${{ packageManager }}-${{ fileHash }} タグ: */pom.xml ── Caching Packages 依存性 上記のスナップを以下に置き換えました。 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 こちらはこちら ↓ タイプ: ドキュメンタリーに1時間を費やすことは、あなたが努力の日々を節約するのに役立ちます。 Thoroughly read the documentation of actions. Pin Your Dependency バージョン このセクションでは、一般的なアドバイスを取り、GitHub ワークフローのバージョンに適用します. You find versions in at least two places: the OCI image and GitHub Actions' version. You may have noticed the 前回の記事では、この時点で、 時間が経つにつれて、さまざまなライブラリのバージョンが最新のバージョンに表示されます. It could cause a failure during the workflow execution, or worse, change the output in ways you't notice until it's too late. 特定のバージョンを設定するのが良いでしょう. チェック (利用可能なすべての画像) runs-on: ubuntu-latest ubuntu-24.04 https://github.com/actions/runner-images アクションのバージョニングは、GitHub レポの参照を指すように異なります:タグまたはコミット SHA ですが、OCI イメージは GitHub の手にありますが、そのアクションはそのプロバイダーの責任です。 pin to a commit です。 must jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@08c6903 #1 Pin to a specific commit(特定のコミットにピン) ヒント:セキュリティを真剣に考えて、 pin actions to a specific commit. 仕事の概要を使う あなたのワークフローの各ステップは、おそらく多くのログを出力します。通常のワークフローでは、ログラインの合計量はかなり大きいかもしれません。それらのいくつかは役に立ちますが、いくつかはそうではありませんが、標準の出力と標準的なエラーがあるため、すべてが同じ場所に終わります。 , 実行テストの数またはコードカバーの割合、もしあなたがこれらのデータを別の場所に送信しない場合 GitHub は、あなたの求めるデータを仕事の概要に追加することを簡単にする。 エジ ワークフロー実行の概要ページに表示されるように、各タスクのためのカスタマイズされたマークダウンを設定できます. ワークフロー実行の概要ページを使用して、テスト結果の概要などのユニークなコンテンツを表示し、グループ化できますので、ワークフロー実行の結果を表示しているユーザーは、実行に関連する重要な情報を、例えば失敗を表示するためにログにアクセスする必要はありません。 Job Summaries は GitHub で味わった Markdown をサポートし、Markdown コンテンツを GITHUB_STEP_SUMMARY 環境ファイルに一歩ずつ追加できます。 仕事の概要を追加する ワークフロー実行の概要ページに表示されるように、各タスクのためのカスタマイズされたマークダウンを設定できます. ワークフロー実行の概要ページを使用して、テスト結果の概要などのユニークなコンテンツを表示し、グループ化できますので、ワークフロー実行の結果を表示しているユーザーは、実行に関連する重要な情報を、例えば失敗を表示するためにログにアクセスする必要はありません。 Job summaries support GitHub flavored Markdown, and you can add your Markdown content for a step to the 環境ファイル 仕事のあらゆるステップにユニークです。 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 THE は: 結果 ↓ タイプ: 開発者の経験を高めるために Use GitHub job summary ワークフローのライフサイクルを理解 ワークフローはステップを連続的に実行します。失敗したステップは、残りのすべてのステップをキャンセルし、ワークフローは終了します。 上記の例では、次のいずれかのステップが失敗した場合、テストの概要は全く得られません。 条件です。 Failure if 次のステータスチェック関数を if conditionals で表現として使用できます. A default status check of success() is applied unless you include one of these functions. ステータスチェック機能 次のステータスチェック関数を表現として使用できます。 デフォルトステータスチェック(Default Status Check) これらの機能のいずれかを含まない限り、適用されます。 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 STEPのIDを設定する テストステップが成功した場合のみ実行 それは単純な例に過ぎませんが、興味深い選択肢を提供しています。 ↓ タイプ: あなたの利益に使ってください。 Know workflows' lifecycle 地元テスト 多くの組織が厳格なGitHubのルールを適用しています。最も広範囲に広がっているのは、あなたが押し付けることができないことです。 : すべてのコミットはリクエストを経なければなりません。既存のプロジェクトには意味がありますが、プロジェクトの開始が迅速に再起動するのを防ぎ、コミットの履歴を保持します。 master アクションプロジェクトが来る: 「グローバルで考え、地元で行動する」 GitHub アクションをローカルに実行! なぜこれをしたいのか? 2 つの理由: - 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 - I love making. However, I also hate repeating myself. With act, you can use the GitHub Actions defined in your .github/workflows/ to replace your Makefile! 現地のタスクランナー - 私は作るのが大好きです。 ■Act to Introduction 「グローバルで考え、地元で行動する」 GitHub アクションをローカルに実行! なぜこれをしたいのか? 2 つの理由: 迅速なフィードバック - あなたがあなたの .github / workflows / ファイル(または組み込まれた GitHub アクションへの変更)にあなたが行っている変更をテストするために毎回コミットする必要があるのではなく、あなたはアクションを使用してアクションをローカルに実行することができます。 Local Task Runner - I love making. However, I also hate repeating myself. With act, you can use the GitHub Actions defined in your .github/workflows/ to replace your Makefile! 現地のタスクランナー - 私は作るのが大好きです。 ■Act to Introduction 正しいイベントに従ってワークフローを起動する 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 I could write a few posts on ドキュメンタリーを読み取ることをお任せします。 act ↓ タイプ: フィードバックサイクルの時間を短縮する Test your workflows locally 概要 正しいセマンティクスを用いて、ワークフローとアクションを区別します。 アドホックコマンドよりも GitHub Actions を好む GitHub アクションを選択する際は、他の依存性を選択する際と同じように慎重にしてください。 あなたが使用する各アクションのドキュメントを注意深く読んでください。 特定のコミットにピンアクション。 GitHubのワークシートを使用して、開発者体験を向上させます。 ワークフローのライフサイクルを知る あなたのワークフローを現地でテストします。 To go further: ワークフローについて GitHub アクション GitHub アクションマーケット ランナー画像 仕事の概要を追加 ステータスチェック機能 INTRODUCTION TO ACT