GitHub Actionsのワークフローコマンド

ワークフローコマンドについて

アクションは、 環境変数を設定する、他のアクションに利用される値を出力する、デバッグメッセージを出力ログに追加するなどのタスクを行うため、ランナーマシンとやりとりできます。

ほとんどのワークフローコマンドは特定の形式で echo コマンドを使用しますが、他のワークフローコマンドはファイルへの書き込みによって呼び出されます。 詳しい情報については、「環境ファイル」を参照してください。

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

ワークフローコマンドを使ったツールキット関数へのアクセス

actions/toolkitには、ワークフローコマンドとして実行できる多くの関数があります。 ::構文を使って、YAMLファイル内でワークフローコマンドを実行してください。それらのコマンドはstdoutを通じてランナーに送信されます。 たとえば、コードを使用して出力を設定する代わりに、以下のようにします。

core.setOutput('SELECTED_COLOR', 'green');

ワークフローで set-output コマンドを使用して、同じ値を設定できます。

      - name: Set selected color
        run: echo '::set-output name=SELECTED_COLOR::green'
        id: random-color-generator
      - name: Get color
        run: echo "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

以下の表は、ワークフロー内で使えるツールキット関数を示しています。

出力パラメータの設定

::set-output name={name}::{value}

アクションの出力パラメータを設定します。

あるいは、出力パラメータをアクションのメタデータファイル中で宣言することもできます。 詳しい情報については、「GitHub Actions のメタデータ構文」を参照してください。

サンプル

echo "::set-output name=action_fruit::strawberry"

デバッグメッセージの設定

::debug::{message}

デバッグメッセージをログに出力します。 ログでこのコマンドにより設定されたデバッグメッセージを表示するには、ACTIONS_STEP_DEBUG という名前のシークレットを作成し、値を true に設定する必要があります。 詳しい情報については、「デバッグログの有効化」を参照してください。

サンプル

echo "::debug::Set the Octocat variable"

警告メッセージの設定

::warning file={name},line={line},endLine={endLine},title={title}::{message}

警告メッセージを作成し、ログにそのメッセージを出力します。 This message will create an annotation, which can associate the message with a particular file in your repository. Optionally, your message can specify a position within the file.

| Parameter | Value | | :- | :- | | file | Filename | | col | Column number, starting at 1 | | line | Line number, starting at 1 |

サンプル

echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

エラーメッセージの設定

::error file={name},line={line},endLine={endLine},title={title}::{message}

エラーメッセージを作成し、ログにそのメッセージを出力します。 This message will create an annotation, which can associate the message with a particular file in your repository. Optionally, your message can specify a position within the file.

| Parameter | Value | | :- | :- | | file | Filename | | col | Column number, starting at 1 | | line | Line number, starting at 1 |

サンプル

echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

ログの行のグループ化

::group::{title}
::endgroup::

展開可能なグループをログ中に作成します。 グループを作成するには、groupコマンドを使ってtitleを指定してください。 groupとendgroupコマンド間でログに出力したすべての内容は、ログ中の展開可能なエントリ内にネストされます。

サンプル

echo "::group::My title"
echo "Inside group"
echo "::endgroup::"

ログ中での値のマスク

::add-mask::{value}

値をマスクすることにより、文字列または値がログに出力されることを防ぎます。 空白で分離された、マスクされた各語は "*" という文字で置き換えられます。 マスクの value には、環境変数または文字列を持ちいることができます。

文字列をマスクするサンプル

ログに "Mona The Octocat" を出力すると、"***" が表示されます。

echo "::add-mask::Mona The Octocat"

環境変数をマスクするサンプル

変数 MY_NAME または値 "Mona The Octocat" をログに出力すると。"Mona The Octocat" の代わりに "***" が表示されます。

MY_NAME="Mona The Octocat"
echo "::add-mask::$MY_NAME"

ワークフローコマンドの停止と開始

::stop-commands::{endtoken}

ワークフローコマンドの処理を停止します。 この特殊コマンドを使うと、意図せずワークフローコマンドを実行することなくいかなるログも取れます。 たとえば、コメントがあるスクリプト全体を出力するためにログ取得を停止できます。

To stop the processing of workflow commands, pass a unique token to stop-commands. To resume processing workflow commands, pass the same token that you used to stop workflow commands.

::{endtoken}::

Example stopping and starting workflow commands

jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: disable workflow commands
        run: |
          echo '::warning:: this is a warning'
          echo "::stop-commands::`echo -n ${{ github.token }} | sha256sum | head -c 64`"
          echo '::warning:: this will NOT be a warning'
          echo "::`echo -n ${{ github.token }} | sha256sum | head -c 64`::"
          echo '::warning:: this is a warning again'

pre及びpostアクションへの値の送信

save-stateコマンドを使って、ワークフローのpre:あるいはpost:アクションと共有するための環境変数を作成できます。 たとえば、pre:アクションでファイルを作成し、そのファイルの場所をmain:アクションに渡し、post:アクションを使ってそのファイルを削除できます。 あるいは、ファイルをmain:アクションで作成し、そのファイルの場所をpost:アクションに渡し、post:アクションを使ってそのファイルを削除することもできます。

複数のpre:あるいはpost:アクションがある場合、保存された値にアクセスできるのはsave-stateが使われたアクションの中でのみです。 post:アクションに関する詳しい情報については「GitHub Actionsのためのメタデータ構文」を参照してください。

save-stateコマンドはアクション内でしか実行できず、YAMLファイルでは利用できません。 保存された値は、STATE_プレフィックス付きで環境変数として保存されます。

以下の例はJavaScriptを使ってsave-stateコマンドを実行します。 結果の環境変数はSTATE_processIDという名前になり、12345という値を持ちます。

console.log('::save-state name=processID::12345')

そして、STATE_processID変数はmainアクションの下で実行されるクリーンアップスクリプトからのみ利用できます。 以下の例はmainを実行し、JavaScriptを使って環境変数STATE_processIDに割り当てられた値を表示します。

console.log("The running PID from the main action is: " +  process.env.STATE_processID);

環境ファイル

ワークフローの実行中に、ランナーは特定のアクションを実行する際に使用できる一時ファイルを生成します。 これらのファイルへのパスは、環境変数を介して公開されます。 コマンドを適切に処理するには、これらのファイルに書き込むときに UTF-8 エンコーディングを使用する必要があります。 複数のコマンドを、改行で区切って同じファイルに書き込むことができます。

steps:
  - run: echo "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

環境変数の設定

echo "{name}={value}" >> $GITHUB_ENV

Creates or updates an environment variable for any steps running next in a job. The step that creates or updates the environment variable does not have access to the new value, but all subsequent steps in a job will have access. 環境変数では、大文字と小文字が区別され、句読点を含めることができます。

サンプル

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> $GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      echo "${{ env.action_state }}" # This will output 'yellow'

複数行の文字列

複数行の文字列の場合、次の構文で区切り文字を使用できます。

{name}<<{delimiter}
{value}
{delimiter}

サンプル

この例では、区切り文字として EOF を使用し、JSON_RESPONSE 環境変数を cURL レスポンスの値に設定します。

steps:
  - name: Set the value
    id: step_one
    run: |
      echo 'JSON_RESPONSE<<EOF' >> $GITHUB_ENV
      curl https://httpbin.org/json >> $GITHUB_ENV
      echo 'EOF' >> $GITHUB_ENV

システムパスの追加

echo "{path}" >> $GITHUB_PATH

Prepends a directory to the system PATH variable and automatically makes it available to all subsequent actions in the current job; the currently running action cannot access the updated path variable. ジョブに現在定義されているパスを見るには、ステップもしくはアクション中でecho "$PATH"を使うことができます。

サンプル

この例は、ユーザの$HOME/.local/binディレクトリをPATHに追加する方法を示しています。

echo "$HOME/.local/bin" >> $GITHUB_PATH