GitHub Actions の再利用可能なワークフローでGITHUB_OUTPUT の変数、値を動的に出力する

実施環境

前提条件

• GitHub のアカウントを持っていること

GITHUB_OUTPUT とは

GitHub Actions の GITHUB_OUTPUT は、ワークフロー内のステップから出力を設定し後続のステップやジョブでその出力を参照する機能です。この機能を使うことで、異なるジョブ、ステップ間で実行結果などのデータを共有できます。例えば、ステップ内で計算した結果を GITHUB_OUTPUT に設定し、次のステップでその結果を利用しパラメーターを設定する、条件分岐に利用するなどの処理を行えます。GITHUB_OUTPUT は同じジョブ内の後続ステップや、ジョブ間でデータを渡す際に使用できます。再利用可能なワークフローでも GITHUB_OUTPUT を設定でき、呼び出し元ワークフローでその出力を参照することによりワークフローの柔軟性と再利用性が向上します。

ワークフロー間で複数の動的な出力を出したい

GitHub Actions のmatrix などを利用する場合、固定の変数名ではなく複数の出力について設定したいケースがあります。また、workflow_call やカスタムアクション間で値の出力を変えたいケースもあります。例えば、サービスごとの入力値を使いデプロイをしたい、入力値を渡して加工した値を呼び出し元で受け取りたい、といった場合があります。このような時に同じ処理を複数回繰り返すのは保守性の観点で推奨されません。そこで、GitHub Actions ではGITHUB_OUTPUT をうまく使うことで、動的な変数、値をGITHUB_OUTPUT に設定できます。

今回の構成

今回はメインで動かすワークフローファイルから再利用可能なワークフローを呼び出し入力値を渡します。その渡した値に応じて設定値を変更する簡単なサンプルを作成します。

ワークフローファイルを作成し実行する

初めに呼び出し元のワークフローファイルと再利用可能なワークフローを作成します。今回は呼び出し元のワークフローファイルを main.yaml、再利用可能なワークフローを test.yaml とします。

name: Caller Workflow
on:
  push:

jobs:
  call-workflow:
    name: Call workflow
    strategy:
      matrix:
        test:
          - value: hogehoge
          - value: fugafuga
    uses: ./.github/workflows/test.yaml
    with:
      example_input: ${{ matrix.test.value }}

  output-variables:
    name: Output variables
    needs: call-workflow
    runs-on: ubuntu-latest
    steps:
      - name: Output variables
        run: |
          echo "hogehoge:  ${{ needs.call-workflow.outputs.hogehoge }}"
          echo "fugafuga:  ${{ needs.call-workflow.outputs.fugafuga }}"

name: Reusable workflow
on:
  workflow_call:
    inputs:
      example_input:
        required: true
        type: string
    outputs:
      hogehoge:
        value: ${{ jobs.example-job.outputs.hogehoge }}
      fugafuga:
        value: ${{ jobs.example-job.outputs.fugafuga }}

jobs:
  example-job:
    runs-on: ubuntu-latest
    env:
      repository: kdkwakaba
    outputs:
      hogehoge: ${{ steps.hogehoge.outputs.hogehoge }}
      fugafuga: ${{ steps.hogehoge.outputs.fugafuga }}
    steps:
      - name: Add GITHUB_OUTPUT
        id: hogehoge
        run: echo "${{ inputs.example_input }}=${{ env.repository }}/${{ inputs.example_input }}" >> $GITHUB_OUTPUT

呼び出し元のワークフローではmatrix を使い、入力値を変えて再利用可能なワークフローを実行します。その後、needs で依存関係を作り再利用可能なワークフローで出力された変数を出力しています。再利用可能なワークフローでは、inputs で受け取った値を利用し、GITHUB_OUTPUT に値を格納しています。格納後はジョブのoutputs、workflow_call のoutputs を使い、呼び出し元のワークフローからoutputs の値を参照できるよう設定しています。両方のoutputs を設定しないと、呼び出し元でoutputs を参照できないため忘れずに設定します。

ワークフローファイルを作成後、GitHub へpush しワークフローを実行します。GITHUB_OUTPUT への格納、変数出力で動的な変数名、値が入っていることを確認します。

実行結果から、もう一方のジョブから outputs の上書きがされていないこともわかります。この挙動をうまく利用することで呼び出し元へ動的な値の受け渡しも可能になります。

この方法の制約

今回の方法ではGITHUB_OUTPUT の出力に動的な変数、値を設定できますが制約もあります。outputs はキー値に変数を利用できないため、キー値を動的に設定することはできません。workflow_call の変数も同様です。そのため、workflow_call やカスタムアクションで動的な出力を行いたい場合、変数名を決め打ちで設定する必要があります。ある程度決まった値について、動的に値を設定したい、などの需要がある時にこのような方法を利用できます。

まとめ

• GITHUB_OUTPUT では決められたパラメーターだけでなく動的な変数、値を設定できる
• workflow_call で呼び出した場合、呼び出し先でoutputs を設定しないと呼び出し元でoutputs を参照できない
• 変数名、値は動的に設定できるが、outpus の変数は動的に設定できないため固定のパラメーターを指定する必要がある

参考資料

• ワークフローの再利用