Skip to main content

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

ワークフロー内あるいはアクションのコード内でシェルコマンドを実行する際には、ワークフローコマンドを利用できます。

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

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

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

Shell
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
pwsh
Write-Output "::workflow-command parameter1={data},parameter2={data}::{command value}"

注: ワークフロー コマンドとパラメーター名では、大文字と小文字は区別されません。

警告: コマンド プロンプトを使用している場合は、ワークフロー コマンドを使うときに二重引用符 (") を省略してください。

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

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

JavaScript
core.error('Missing semicolon', {file: 'app.js', startLine: 1})

例: エラーの注釈の作成

ワークフローで error コマンドを使用して、同じエラー注釈を作成できます。

YAML
      - name: Create annotation for build error
        run: echo "::error file=app.js,line=1::Missing semicolon"
YAML
      - name: Create annotation for build error
        run: Write-Output "::error file=app.js,line=1::Missing semicolon"

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

ツールキット関数等価なワークフローのコマンド
core.addPathGITHUB_PATH 環境ファイルを使用してアクセス可能
core.debugdebug
core.noticenotice
core.errorerror
core.endGroupendgroup
core.exportVariableGITHUB_ENV 環境ファイルを使用してアクセス可能
core.getInputINPUT_{NAME} 環境変数を使用してアクセス可能
core.getStateSTATE_{NAME} 環境変数を使用してアクセス可能
core.isDebugRUNNER_DEBUG 環境変数を使用してアクセス可能

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

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

Code
::debug::{message}

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

Shell
echo "::debug::Set the Octocat variable"
pwsh
Write-Output "::debug::Set the Octocat variable"

通知メッセージの設定

通知メッセージを作成し、ログにそのメッセージを出力します。 このメッセージは注釈を作成します。これにより、リポジトリ内の特定のファイルにメッセージを関連付けることができます。 必要に応じて、メッセージでファイル内の位置を指定できます。

Code
::notice file={name},line={line},endLine={endLine},title={title}::{message}
パラメーター
titleカスタム タイトル
fileファイル名
col列番号 (1 から始まる)
endColumn終わりの列番号
line行番号 (1 から始まる)
endLine終わりの行番号

例: 通知メッセージの設定

Shell
echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
Write-Output "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

警告メッセージの設定

警告メッセージを作成し、ログにそのメッセージを出力します。 このメッセージは注釈を作成します。これにより、リポジトリ内の特定のファイルにメッセージを関連付けることができます。 必要に応じて、メッセージでファイル内の位置を指定できます。

Code
::warning file={name},line={line},endLine={endLine},title={title}::{message}
パラメーター
titleカスタム タイトル
fileファイル名
col列番号 (1 から始まる)
endColumn終わりの列番号
line行番号 (1 から始まる)
endLine終わりの行番号

例: 警告メッセージの設定

Shell
echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
Write-Output "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

エラーメッセージの設定

エラーメッセージを作成し、ログにそのメッセージを出力します。 このメッセージは注釈を作成します。これにより、リポジトリ内の特定のファイルにメッセージを関連付けることができます。 必要に応じて、メッセージでファイル内の位置を指定できます。

Code
::error file={name},line={line},endLine={endLine},title={title}::{message}
パラメーター
titleカスタム タイトル
fileファイル名
col列番号 (1 から始まる)
endColumn終わりの列番号
line行番号 (1 から始まる)
endLine終わりの行番号

例: エラー メッセージの設定

Shell
echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
pwsh
Write-Output "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"

ログの行のグループ化

展開可能なグループをログ中に作成します。 グループを作成するには、group コマンドを使用して title を指定します。 ログに出力する groupendgroup コマンド間のすべての内容は、ログで展開可能なエントリ内で入れ子になります。

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

例: ログの行のグループ化

YAML
jobs:
  bash-example:
    runs-on: ubuntu-latest
    steps:
      - name: Group of log lines
        run: |
            echo "::group::My title"
            echo "Inside group"
            echo "::endgroup::"
YAML
jobs:
  powershell-example:
    runs-on: windows-latest
    steps:
      - name: Group of log lines
        run: |
            Write-Output "::group::My title"
            Write-Output "Inside group"
            Write-Output "::endgroup::"

ワークフローの実行ログ中の折りたたみ可能なグループ

ログ中での値のマスク

Code
::add-mask::{value}

値をマスクすることにより、文字列または値がログに出力されることを防ぎます。 空白で区切られた、マスクされる各単語は、* という文字に置き換えられます。 マスクの value には、環境変数または文字列を使用できます。 値をマスクすると、シークレットとして扱われ、ランナーで編集されます。 たとえば、値をマスクした後は、その値を出力として設定することはできません。

例: 文字列のマスク

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

Shell
echo "::add-mask::Mona The Octocat"
pwsh
Write-Output "::add-mask::Mona The Octocat"

警告: シークレットをビルド ログに出力したり、その他のワークフロー コマンド内で使ったりする前に、シークレットを "add-mask" に必ず登録してください。

例: 環境変数のマスク

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

YAML
jobs:
  bash-example:
    runs-on: ubuntu-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: bash-version
        run: echo "::add-mask::$MY_NAME"
YAML
jobs:
  powershell-example:
    runs-on: windows-latest
    env:
      MY_NAME: "Mona The Octocat"
    steps:
      - name: powershell-version
        run: Write-Output "::add-mask::$env:MY_NAME"

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

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

Code
::stop-commands::{endtoken}

ワークフロー コマンドの処理を停止するには、固有のトークンを stop-commands に渡します。 ワークフロー コマンドの処理を再開するには、ワークフロー コマンドを停止するために使用したトークンと同じものを渡します。

警告: ランダムに生成された、実行ごとに固有のトークンを使用するようにしてください。

Code
::{endtoken}::

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

YAML
jobs:
  workflow-command-job:
    runs-on: ubuntu-latest
    steps:
      - name: Disable workflow commands
        run: |
          echo '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          stopMarker=$(uuidgen)
          echo "::stop-commands::$stopMarker"
          echo '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          echo "::$stopMarker::"
          echo '::warning:: This is a warning again, because stop-commands has been turned off.'
YAML
jobs:
  workflow-command-job:
    runs-on: windows-latest
    steps:
      - name: Disable workflow commands
        run: |
          Write-Output '::warning:: This is a warning message, to demonstrate that commands are being processed.'
          $stopMarker = New-Guid
          Write-Output "::stop-commands::$stopMarker"
          Write-Output '::warning:: This will NOT be rendered as a warning, because stop-commands has been invoked.'
          Write-Output "::$stopMarker::"
          Write-Output '::warning:: This is a warning again, because stop-commands has been turned off.'

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

GITHUB_STATE にあるファイルに書き込むことで、ワークフローの pre: または post: アクションと共有するための環境変数を作成できます。。 たとえば、pre: アクションでファイルを作成し、そのファイルの場所を main: アクションに渡し、post: アクションを使用してファイルを削除できます。 あるいは、main: アクションでファイルを作成し、そのファイルの場所を post: アクションに渡し、さらに post: アクションを使用してファイルを削除することもできます。

複数の pre: または post: アクションがある場合は、GITHUB_STATE に書き込まれたアクションで保存された値にのみアクセスできます。 post: アクションについて詳しくは、「GitHub Actions のメタデータ構文」をご覧ください。

GITHUB_STATE ファイルはアクション内でのみ使用できます。 保存された値は、STATE_ というプレフィックスが付いた環境変数として保存されます。

この例では、JavaScript を使用して GITHUB_STATE ファイルに書き込みます。 結果の環境変数は、STATE_processID という名前になり、値が 12345 になります。

JavaScript
import * as fs from 'fs'
import * as os from 'os'

fs.appendFileSync(process.env.GITHUB_STATE, `processID=12345${os.EOL}`, {
  encoding: 'utf8'
})

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

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

環境ファイル

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

次の例のほどんどのコマンドでは、エコー文字列に二重引用符を使います。これにより、シェル変数名に対して $ などの文字の補間が試行されます。 引用符で囲まれた文字列でリテラル値を常に使用するには、代わりに単一引用符を使用できます。

注: PowerShell バージョン 5.1 以下 (shell: powershell) では UTF-8 が既定で使用されないため、UTF-8 エンコードを指定する必要があります。 次に例を示します。

YAML
jobs:
  legacy-powershell-example:
    runs-on: windows-latest
    steps:
      - shell: powershell
        run: |
          "mypath" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append

PowerShell Core バージョン 6 以上 (shell: pwsh) では、UTF-8 が既定で使用されます。 次に例を示します。

YAML
jobs:
  powershell-core-example:
    runs-on: windows-latest
    steps:
      - shell: pwsh
        run: |
          "mypath" >> $env:GITHUB_PATH

環境変数の設定

Shell
echo "{environment_variable_name}={value}" >> $GITHUB_ENV
  • PowerShell バージョン 6 以上を使用:

    pwsh
    "{environment_variable_name}={value}" >> $env:GITHUB_ENV
  • PowerShell バージョン 5.1 以下を使用:

    powershell
    "{environment_variable_name}={value}" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append

環境変数を定義または更新し、これを GITHUB_ENV 環境ファイルに書き込むことで、ワークフロー ジョブの後続のステップで環境変数が利用できるようになります。 環境変数を作成または更新するステップは、新しい値にアクセスできませんが、ジョブにおける後続のすべてのステップはアクセスできます。 環境変数の名前では、大文字と小文字が区別され、句読点を含めることができます。 詳しくは、「環境変数」をご覧ください。

YAML
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'
YAML
steps:
  - name: Set the value
    id: step_one
    run: |
      "action_state=yellow" >> $env:GITHUB_ENV
  - name: Use the value
    id: step_two
    run: |
      Write-Output "${{ env.action_state }}" # This will output 'yellow'

複数行の文字列

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

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

警告: ランダムに生成された、実行ごとに固有の区切り記号を使用するようにしてください。 詳細については、「スクリプト インジェクションのリスクを理解する」を参照してください。

この例では、区切り文字として EOF を使用し、JSON_RESPONSE 環境変数を curl の応答の値に設定します。

YAML
steps:
  - name: Set the value in bash
    id: step_one
    run: |
      echo 'JSON_RESPONSE<<EOF' >> $GITHUB_ENV
      curl https://example.com >> $GITHUB_ENV
      echo 'EOF' >> $GITHUB_ENV
YAML
steps:
  - name: Set the value in pwsh
    id: step_one
    run: |
      "JSON_RESPONSE<<EOF" >> $env:GITHUB_ENV
      (Invoke-WebRequest -Uri "https://example.com").Content >> $env:GITHUB_ENV
      "EOF" >> $env:GITHUB_ENV
    shell: pwsh

出力パラメータの設定

ステップの出力パラメーターを設定します。 後で出力値を取得するには、ステップで id を定義する必要があることに注意してください。

Shell
echo "{name}={value}" >> $GITHUB_OUTPUT
pwsh
"{name}=value" >> $env:GITHUB_OUTPUT

この例では、SELECTED_COLOR 出力パラメーターを設定し、後でそれを取得する方法を示します。

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

この例では、SELECTED_COLOR 出力パラメーターを設定し、後でそれを取得する方法を示します。

YAML
      - name: Set color
        id: random-color-generator
        run: |
            "SELECTED_COLOR=green" >> $env:GITHUB_OUTPUT
      - name: Get color
        run: Write-Output "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"

ジョブの概要の追加

Shell
echo "{markdown content}" >> $GITHUB_STEP_SUMMARY
pwsh
"{markdown content}" >> $env:GITHUB_STEP_SUMMARY

ジョブごとにいくつかのカスタム Markdown を設定して、ワークフロー実行の概要ページに表示されるようにすることができます。 ジョブの概要を使用して、テスト結果の概要といった独自の内容を表示およびグループ化できます。これにより、ワークフロー実行の結果を表示するユーザーが、実行に関連する重要な情報 (エラーなど) を確認するためにログを調べる必要がなくなります。

ジョブの概要では GitHub Flavored Markdown がサポートされていて、ステップの Markdown コンテンツを GITHUB_STEP_SUMMARY 環境ファイルに追加できます。 GITHUB_STEP_SUMMARY は、ジョブのステップごとに固有のものです。 GITHUB_STEP_SUMMARY が参照するステップごとのファイルについて詳しくは、「環境ファイル」をご覧ください。

ジョブが完了すると、ジョブにおけるすべてのステップの概要が 1 つのジョブの概要にグループ化され、ワークフロー実行の概要ページに表示されます。 複数のジョブが概要を生成する場合、ジョブの概要の順序はジョブの完了時間順になります。

Shell
echo "### Hello world! :rocket:" >> $GITHUB_STEP_SUMMARY
pwsh
"### Hello world! :rocket:" >> $env:GITHUB_STEP_SUMMARY

Markdown の概要の例

複数行の Markdown コンテンツ

複数行の Markdown コンテンツの場合は、>> を使用して、現在のステップのコンテンツを連続して追加できます。 追加操作のたびに、改行文字が自動的に追加されます。

- name: Generate list using Markdown
  run: |
    echo "This is the lead in sentence for the list" >> $GITHUB_STEP_SUMMARY
    echo "" >> $GITHUB_STEP_SUMMARY # this is a blank line
    echo "- Lets add a bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- Lets add a second bullet point" >> $GITHUB_STEP_SUMMARY
    echo "- How about a third one?" >> $GITHUB_STEP_SUMMARY
- name: Generate list using Markdown
  run: |
    "This is the lead in sentence for the list" >> $env:GITHUB_STEP_SUMMARY
    "" >> $env:GITHUB_STEP_SUMMARY # this is a blank line
    "- Lets add a bullet point" >> $env:GITHUB_STEP_SUMMARY
    "- Lets add a second bullet point" >> $env:GITHUB_STEP_SUMMARY
    "- How about a third one?" >> $env:GITHUB_STEP_SUMMARY

ジョブの概要の上書き

現在のステップのすべてのコンテンツをクリアするには、> を使用して、以前に追加したコンテンツを上書きします。

- name: Overwrite Markdown
  run: |
    echo "Adding some Markdown content" >> $GITHUB_STEP_SUMMARY
    echo "There was an error, we need to clear the previous Markdown with some new content." > $GITHUB_STEP_SUMMARY
- name: Overwrite Markdown
  run: |
    "Adding some Markdown content" >> $env:GITHUB_STEP_SUMMARY
    "There was an error, we need to clear the previous Markdown with some new content." > $env:GITHUB_STEP_SUMMARY

ジョブの概要の削除

現在のステップの概要を完全に削除するには、GITHUB_STEP_SUMMARY が参照するファイルを削除します。

- name: Delete all summary content
  run: |
    echo "Adding Markdown content that we want to remove before the step ends" >> $GITHUB_STEP_SUMMARY
    rm $GITHUB_STEP_SUMMARY
- name: Delete all summary content
  run: |
    "Adding Markdown content that we want to remove before the step ends" >> $env:GITHUB_STEP_SUMMARY
    rm $env:GITHUB_STEP_SUMMARY

ステップが完了すると、ジョブの概要がアップロードされ、後続のステップは以前にアップロードされた Markdown コンテンツを変更できません。 概要では、誤って追加された可能性があるシークレットが自動的にマスクされます。 ジョブの概要に削除する必要がある機密情報が含まれている場合は、ワークフロー実行全体を削除して、そのジョブの概要をすべて削除できます。 詳しくは、「ワークフロー実行の削除」をご覧ください。

ステップの分離と制限

ジョブの概要はステップ間で分離されていて、各ステップのサイズは最大 1 MiB に制限されています。 分離がステップ間で適用されるため、1 つのステップにおいて Markdown の形式が誤っている可能性があっても、後続のステップで Markdown のレンダリングが中断することはありません。 ステップに 1 MiB を超えるコンテンツが追加された場合、ステップのアップロードは失敗し、エラーの注釈が作成されます。 ジョブの概要のアップロード エラーは、ステップまたはジョブの全体的な状態には影響しません。 ジョブごとに、ステップのジョブの概要が最大 20 件表示されます。

システムパスの追加

システムの PATH 変数の先頭にディレクトリを追加し、自動的に現在のジョブにおける後続のすべてのアクションで利用できるようにします。現在実行中のアクションは、更新されたパス変数にアクセスできません。 ジョブに現在定義されているパスを確認するには、ステップまたはアクションで echo "$PATH" を使うことができます。

Shell
echo "{path}" >> $GITHUB_PATH
pwsh
"{path}" >> $env:GITHUB_PATH

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

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

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

pwsh
"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH