GitHub Actions で再利用可能なワークフローを作成

再利用可能なワークフローは、DRY (Don’t Repeat Yourself) 原則を取り入れ、標準化を導入し、ベストプラクティスを着実に実装することを可能にします。これらのワークフローは開発者ジャーニーを円滑にするため、過度の制限を課すことなく、プロセスをさらに合理的かつ効率的にします。ガイドの中ほどで Deutsche Vermögensberatung AG (DVAG) が参加し、再利用可能なワークフローを最大限に活用するためのアドバイスを提供してくれます。

このガイドの学習内容

• 再利用可能なワークフローの用途と利点

• 再利用可能なワークフローの作成に必要な基本的なコンポーネントと構文

• 再利用可能なワークフローを呼び出すための URL 構造と構文

• 再利用可能なワークフローを個別のリポジトリにあるプロジェクトに組み込む方法

再利用可能なワークフローの概要と仕組み

再利用可能なワークフローは、他のワークフローが実行できる GitHub Actions ファイルです。単一のワークフローが複数の再利用可能なワークフローを呼び出すことができ、それぞれの参照は 1 行の YAML のみです。つまり「呼び出す側」のワークフローは、わずか数行の YAML しか含んでいなくても、多数のタスクを実行することもあります。「呼び出される側」のジョブやステップを自身の一部であるかのように扱い、「呼び出される側」のワークフローを完全に実行するからです。さらに、ワークフローは最大 4 レベルまでネストすることが可能です。

再利用可能なワークフローの利点

再利用可能なワークフローには次のような利点があります。

• 冗長性を排除できる

• 再利用できるためワークフローを迅速に作成できる

• 一元管理できる再利用可能なワークフローのライブラリを使用し、メンテナンスを減らしたり、セキュリティを強化したりできる

• 適切に設計され、テストされ、その効果が実証されているワークフローの使用を推進できる

上記の利点を考慮しながらランナーグループと組み合わせることで、整備されたパスを作成し、開発者がインフラストラクチャの管理や既存のワークフローの再作成でなく、目下の作業に集中して取り組めるようにできます。

当社では、ワークフローを monorepo に一元化しました。一貫性と品質を長期にわたって保証できるよう、全ての変更にコード所有者による承認を必須にすると同時に、特定のワークフローに特化した所有権を可能にしました。 セマンティック バージョニングを使用し、1.x.x バージョン スキームに準拠して、互換性を破る変更を回避しています。通常は、ワークフローの新バージョンを毎週リリースします。自動マージ機能を使用してアップデートが滞りなく行われるようにし、メイン ブランチとテスト リポジトリの両方でテストしています。また、リポジトリ全体でのワークフローの使用状況を積極的に監視し、ワークフローが効果的に使用されていることを確認しています。

Florian Koch // IT Platform Lead // Deutsche Vermögensberatung (DVAG)

再利用可能なワークフローのコンポーネント

トリガーとなるイベント

ワークフローを再利用できるようにするには、on に次の値を含める必要があります: workflow_call:

on:
  workflow_call:

インプットの定義

再利用可能なワークフローでインプットとシークレットを定義し、それらを呼び出し側のワークフローから受け取ることができます。名前付きシークレットを渡すには、inputs および secrets キーワードを使用します。詳しくは、シークレットと変数で CI/CD を保護する方法についてのガイドを参照してください。以下は、再利用可能なワークフローの例にコメントを入れたものです。

on:  # Specifies the event triggering the workflow
  workflow_call:  # Indicates that this is a reusable workflow
    inputs:  # Defines the inputs that can be passed from the caller workflow
      config-path:  # Name of the input
        required: true  # Specifies that this input is mandatory
        type: string  # Specifies the type of the input
    secrets:  # Defines the secrets that can be passed from the caller workflow
      envPAT:  # Name of the secret
        required: true  # Specifies that this secret is mandatory

上の例の envPAT は、本番環境に追加された環境シークレットです。つまり、この環境がジョブ内で参照されます。

名前付きシークレットを渡す

名前付きのインプットを呼び出される側のワークフローに渡すには、with キーワードをジョブで使用します。名前付きシークレットを渡すには、secrets キーワードを使用します。インプットの場合、入力値のデータ型は、呼び出されるワークフローで指定されている型 (boolean、number、または string) と一致する必要があります。

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      envPAT: ${{ secrets.envPAT }}

同じ Organization または Enterprise の再利用可能なワークフローを呼び出すワークフローは、inherit キーワードを使用して暗黙的にシークレットを渡すことができます。

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets: inherit

チームやプロジェクト間で再利用可能なワークフローのアップデートを自動的に配布するために、Dependabot を利用しています。 各リリースは自動的にユーザー リポジトリのプルリクエストをトリガーしますが、これは専用の問題で詳細に追跡されます。こうすることにより、ワークフローを更新したユーザー、していないユーザーを常に把握でき、全員が足並みをそろえて最新で効果的なワークフローを使用していることを簡単に確認できます。

Florian Koch // IT Platform Lead // Deutsche Vermögensberatung (DVAG)

再利用可能なアクションを呼び出す

再利用可能なワークフローは uses キーワードを使用して呼び出します。ワークフロー内でアクションを使用する場合とは異なり、再利用可能なワークフローは (ジョブのステップからではなく) ジョブ内で直接呼び出します。再利用可能なワークフローを呼び出すための URL 構造を部分別に見ていきましょう。上の例に次のような行があります。

uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main

上記のコードは、次のような特定の構造に従っているのが分かります。

uses: [OWNER/REPOSITORY PATH]/[.github/workflows/WORKFLOW_FILE]@[REF]

この構造のセグメントには、それぞれ特定の目的があります。

1.uses:

これは GitHub Actions 構文のキーワードの 1 つであり、後続の文字列がアクションや、この例では再利用可能なワークフローなど、再利用可能なコードを参照することを示しています。

2.OWNER:

これは、再利用可能なワークフローがあるリポジトリを所有している GitHub ユーザーまたは Organization を指定します (例: octo-org)。

3.REPOSITORY PATH:

これはリポジトリへのパスです (例: example-repo/).

4..github/workflows/:

これは、GitHub Actions がリポジトリ内のワークフロー定義を見つけるための通常のパスです。GitHub Actions が認識して実行できるように、ワークフローの YAML ファイルは全て、このディレクトリ内に置く必要があります。

5.WORKFLOW_FILE:

これは、ワークフロー定義を含む YAML ファイルそのものを示しています。(例: reusable-workflow.yml).

6.@REF:

これは、ワークフローを使用するブランチ、タグ、またはコミット SHA を示しています。使用するワークフローのバージョンを GitHub Actions に知らせるために、必ず指定する必要があります。これは、ワークフローが時とともに進化していくなか、自分のワークフローでは特定のバージョンが使われるようにする場合に、特に役立ちます (例: @main).

ワークフローを再利用できるようにする方法

以下は、build-test-deploy.yml ワークフロー (自動化の基本モジュールで作成) からの例です。以下では、再利用可能にするためにファイルを更新しました。つまり、workflow_callを追加し、さらに node-versionを設定するパラメーターも定義しました。コード内のコメントに注目してください。

name: build-test-deploy
# Changed 'on' to enable this workflow to be called from other workflows
on:
  workflow_call:
    # Introduced 'inputs' to define parameters that can be passed when calling this workflow
    inputs:
      node-version:
        description: "Node version"
        required: true
        type: string

jobs: 
  build:
    runs-on: ubuntu-latest

    steps: 
      - name: checkout repo
        uses: actions/checkout@v3
      # Modified to use the node-version from the workflow inputs
      - name: use node.js
        uses: actions/setup-node@v3
        with:
          node-version: ${{ inputs.node-version }}

      - run: npm install
      - run: npm run build

  test: 
    needs: build

    runs-on: ubuntu-latest

    steps: 
      - name: checkout repo
        uses: actions/checkout@v3
      # Modified to use the node-version from the workflow inputs
      - name: use node.js
        uses: actions/setup-node@v3
        with:
          node-version: ${{ inputs.node-version }}
          
      - run: npm install
      - run: npm run test

これで、再利用できるように build-test-deploy ワークフローが更新され、再利用可能なワークフローの呼び出し方も理解できました。それでは全てまとめてみましょう。以下のサンプルコードでは、build-test-deploy ワークフローを別のリポジトリにあるワークフローから呼び出しています。

jobs:
  my-job:
    # Importing a reusable workflow from another repository and branch
    uses: organization/repo/.github/workflows/build-test-deploy.yml@main
    # Passing 'node-version' as an input parameter to the reusable workflow
    with:
      node-version: '18.x'

次のガイド: GitHub Actions でワークフローを管理および監視する

GitHub Actions の管理と監視を最適化する準備はできましたか? 詳しいガイドをぜひご覧ください。ワークフローのステータスの分析からリソースの使用状況の追跡まで、GitHub は運用の効率化に必要なツールを提供します。