GitHub Actionsはね、後続ステップで参照できるようにあるステップで出力を定義する方法が、ワークフローコマンドから環境ファイルに変わったんだよ

はじめに

そこもムーンプリンセスなの？¹、nikkieです。

今回はGitHub Actionsネタです。
自作したActionを微調整していたのですが、出力の設定方法が変わったことを知りました。

GitHub Actions、簡単に用語の整理

「ステップ」に関連する用語を整理します。

GitHub Actionsは「ワークフロー」から構築されます。
.github/workflowsにYAMLファイルを書いて定義するので、ワークフローと呼ばれるのかなと理解しています。

ワークフローは「ジョブ」から構成されます。
1つのジョブからも複数のジョブからも構成できます。
ワークフロー定義のYAMLファイルにはjobsというセクションがありますね。

ジョブは1つ以上の「ステップ」からなります。
YAMLのjobsにはstepsを定義しますね。
1つのジョブの実行環境は同じで、ファイルシステムも共通です。
なのであるジョブでライブラリをインストールして、続くステップでライブラリのコマンドを実行できます。

つまり、ステップはジョブを構成するものです。
あるステップから後続のステップへはファイルシステムを通して情報をやり取りできますが、プログラミングでいう"変数を定義"っぽいこともできます。
それが、エントリタイトルの「後続ステップで参照できるようにあるステップで出力を定義」です。
あるコマンドの実行結果を別のステップで参照したいときに、私は使っています。

結論：ステップの出力の定義には、「環境ファイル」を使おう！

2022年10月の以下記事で、一部のワークフローコマンドの廃止がアナウンスされています（私は当時見落としました）。

これまではワークフローコマンドのset-outputでしたが、今後は環境ファイルの$GITHUB_OUTPUTとなります。

We are monitoring telemetry for the usage of these commands and plan to fully disable them on 31st May 2023.

（後半部分）2023年5月末でset-outputを無効化する計画、とのことです。

背景としては

To avoid untrusted logged data to use save-state and set-output workflow commands without the intention of the workflow author we have introduced a new set of environment files to manage state and output.

（前半部分）ワークフロー作成者が意図せずにset-outputワークフローコマンドを使って信頼できないデータが記録されるのを防ぐため、だそうです

定義の仕方が変わるだけで、参照の仕方は変わりません。

廃止される`set-output`ワークフローコマンド

シェルのechoコマンド & 特定の形式の出力でワークフローコマンドが使えます。
https://docs.github.com/ja/actions/using-workflows/workflow-commands-for-github-actions#about-workflow-commands

書式は以下のようになります。

echo "::workflow-command parameter1={data},parameter2={data}::{command value}"

「後続ステップで参照できるようにあるステップで出力を定義」するset-outputコマンドは以下の書式となります（廃止される書き方です）。

echo "::set-output name={key}::{value}"

set-outputコマンドのnameパラメタにkeyを渡す
set-outputコマンドの出力はvalueとする

set-outputコマンドを実行するステップにはIDを付与します。
後続のステップではsteps.<id>.outputs.<key>で参照できます！

# stepsのイメージです
- id: awesome
  run: echo "::set-output name=character::shion"
- run: |
    # あとに続くステップでは ${{ steps.awesome.outputs.character }} でshionを参照できます

こちらを使おう！環境ファイル`$GITHUB_OUTPUT`

https://docs.github.com/ja/actions/using-workflows/workflow-commands-for-github-actions#environment-files

ワークフローの実行中に、ランナーは特定のアクションを実行する際に使用できる一時ファイルを生成します。
これらのファイルへのパスは、環境変数を介して公開されます。

$GITHUB_OUTPUTは「ステップの出力パラメータの設定」に使う環境ファイルです。
環境ファイルには追記のリダイレクトを使って書き込みます。
書式は以下のようになります。

echo "{key}={value}" >> $GITHUB_OUTPUT

set-outputワークフローコマンドを使った例を書き換えてみます。

# stepsのイメージです
- id: awesome
  run: echo "character=shion" >> $GITHUB_OUTPUT
- run: |
    # あとに続くステップでは ${{ steps.awesome.outputs.character }} でshionを参照できます

終わりに

見落としていたset-outputコマンドの廃止に気付き、環境ファイルを使った書き方を確認しました。
知った時点では「廃止、つまり、不可逆な変更なのか！」と驚いたのですが、書き換えてみると環境ファイルを使ったほうが簡単な書式になるので納得感もあります。

この記事でset-outputワークフローコマンドの廃止を知った方、お早めに環境ファイル$GITHUB_OUTPUTに切り替えましょう。
私もいくつかのリポジトリで作業します！

参考文献

GitHub Actionsの用語とset-outputワークフローコマンドの書式は、『Software Design 2020年10月号』第2特集「3ステップでマスターするGitHub Actions」を参照しました。
非常に分かりやすく、GitHub Actionsを自作する上で参考にしている記事です。