ワークフローコマンド
GitHub Actions には少し特殊なワークフローコマンドというものがあります。実態はecho
コマンドですが、出力の形式が決められてます。
ワークフローコマンドには以下のような種類があります。
set-env
set-output
add-path
error
warning
debug
add-mask
set-env
set-env
は環境変数を設定できます。設定した環境変数はその後のステップで使うことができます。これは主に何かしら動的に取得した情報などを元に環境変数を設定したい場合に使います。
jobs:
build:
steps:
# `echo nju33`は動的な情報入力のつもり
- run: echo nju33 | xargs -I{} echo "::set-env name=NAME::{}"
- run: echo "$NAME"
静的な環境変数の設定なら<job-id>.env
や<job-id>.steps.<step-id>.env
での設定がオススメです。
jobs:
build:
env:
FOO: foo
steps:
- run: ...
env:
BAR: bar
set-output
ワークフローでの変数のようなものを定義できます。定義後はsteps.<step-id>.outputs.<value-name>
のような形で、その後のステップで使うことができます。<step-id>
を使う為、ステップにはid
指定が必須です。
以下は例です。
jobs:
build:
steps:
- id: org
run: echo "::set-output name=name::nju33-com"
- run: echo "${{ steps.org.outputs.name }}"
run: echo "${{ steps.org.outputs.name }}"
部分のステップが実行された時、nju33-com
という文字が出力されます。
ところで、「これなら環境変数を使えばいいんじゃないか」と考える人が出てくると思いますが、シェル部分であれば環境変数でも良いです。しかしシェル以外の部分では環境変数を参照できない為、そういった部分ではset-output
で一旦定義してから使います。
そういった部分と言うのは具体的に 1 つ言うと action の inputs の値があります。例えば、actions/checkout では inputs 値の 1 つにrepository
が指定できます。その指定に outputs 値を使うと以下のようになります。
jobs:
build:
steps:
- id: org
run: echo "::set-output name=name::nju33-com"
- run: echo "${{ steps.org.outputs.name }}"
- id: repo
run: echo "::set-output name=name::${{ steps.org.outputs.name }}/sandbox-github-actions-workflow-command"
- uses: actions/checkout@v2
with:
repository: ${{ steps.repo.outputs.name }}
この実行結果は、repository
にnju33-com/sandbox-github-actions-workflow-command
が渡り、actions/checkout
が実行されてます。
set-path
PATH
に追加します。 Node.js プロジェクトでcowsay
というパッケージを使い例を見てみます。ちなみに、このパッケージは牛が何か喋ってるように見せることができる CLI ツールです。
npm
やyarn
を使い実際にパッケージをローカルインストールするとnode_modules/.bin
以下にcowsay
という実行可能ファイルが作られます。
インストール直後では相対パスでnode_modules/.bin/cowsay
と指定する必要がありますが、これをcowsay
だけで実行できるようにしてみます。
以下は例です。 3 つ目のステップでPATH
に追加してます。
jobs:
build:
steps:
- run: |
yarn init -y
yarn add -D cowsay
- run: |
if command -v cowsay > /dev/null; then
cowsay Moo
else
echo cowsay: command not found
fi
- run: echo "::add-path::$(pwd)/node_modules/.bin"
- run: |
if command -v cowsay > /dev/null; then
cowsay Moo
else
echo cowsay: command not found
fi
この実行結果は、最初のステップでcowsay
がローカルインストールされます。次にもしcowsay
コマンドにPATH
が通っていればMoo
と鳴くようにしてますが、まだ通っていないのでcowsay: command not found
と出力されます。
その後、一度add-path
ワークフローコマンドで$(pwd)/node_modules/.bin
という絶対パスを設定し、再度cowsay
コマンドの実行を試みます。
今度はパスが通っているのでMoo
と鳴きます。
_____
< Moo >
-----
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
error
エラーメッセージを表示できます。この形でエラーメッセージを記述すると、実行結果ページで赤い線の目立つ枠でエラーメッセージが表示されます。
jobs:
build:
steps:
- run: echo ::error::error-message
エラーメッセージの他にどのファイル(file
)の何行(line
)何列(col
)目に対してのメッセージなのかを指定できます。(,
の後のスペースを入れないように気を付けます。もしスペースを入れてしまうとうまく解釈されなくなります)
jobs:
build:
steps:
- run: |
echo ::error file=index.js,line=1,col=1::The first line is bad
exit 1
- run: echo foo
詳細にファイル名や行の指定があると、エラーメッセージもより詳細に分かりやすい形で表示されます。
warning
警告メッセージを表示できます。使い方はerror
ワークフローコマンドと同じですが、実行結果ページでメッセージの線が黄色になってます。
jobs:
build:
runs-on: ubuntu-16.04
steps:
- run: echo ::warning::warning-message
- run: echo ::warning file=.github/workflows/warning.yml,line=10,col=14::ubuntu-18.04 使ってね
debug
デバッグ時のみのメッセージを出力します。デバッグ時とはリポジトリのシークレット変数ACTIONS_STEP_DEBUG
をtrue
に設定した状態でワークフローを実行した時のことで、以下のようにやってる事が細かに吐き出されるようになります。(以下はecho 123
したステップのログ)
##[debug]Evaluating condition for step: 'Run echo 123'
##[debug]Evaluating: success()
##[debug]Evaluating success:
##[debug]=> true
##[debug]Result: true
##[debug]Starting: Run echo 123
##[debug]Loading inputs
##[debug]Loading env
Run echo 123
##[debug]/bin/bash -e /home/runner/work/_temp/b85ddda2-9c07-4f5d-80c2-f0b6b46fc9a8.sh
123
##[debug]Finishing: Run echo 123
debug
ワークフローコマンドは以下のように使います。これはdebug-message
と表示する例です。
jobs:
build:
steps:
- run: echo ::debug::debug-message
debug
ワークフローコマンドのメッセージはACTIONS_STEP_DEBUG
がtrue
の状態だと表示されません。
add-mask
渡したメッセージを***
にする事ができます。
jobs:
build:
steps:
- run: echo ::add-mask::foo
実行結果ページで確認すると、::add-mask::***
となってることが分かります。