ワークフローコマンド

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 }}

この実行結果は、repositorynju33-com/sandbox-github-actions-workflow-commandが渡り、actions/checkoutが実行されてます。

set-path

PATHに追加します。 Node.js プロジェクトでcowsayというパッケージを使い例を見てみます。ちなみに、このパッケージは牛が何か喋ってるように見せることができる CLI ツールです。

npmyarnを使い実際にパッケージをローカルインストールすると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_DEBUGtrueに設定した状態でワークフローを実行した時のことで、以下のようにやってる事が細かに吐き出されるようになります。(以下は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_DEBUGtrueの状態だと表示されません

add-mask

渡したメッセージを***にする事ができます。

jobs:
  build:
    steps:
      - run: echo ::add-mask::foo

実行結果ページで確認すると、::add-mask::***となってることが分かります。