注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
ワークフローコマンドについて
アクションは、 環境変数を設定する、他のアクションに利用される値を出力する、デバッグメッセージを出力ログに追� するなどのタスクを行うため、ランナーマシンとやりとりできます。
ほとんどのワークフロー コマンドが特定の形式で echo
コマンドを使用しますが、他のコマンドはファイルへの書き込みによって呼び出されます。 詳しくは、「環境ファイル」を参照してく� さい。
例
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
Write-Output "::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 }}"
- name: Set selected color
run: Write-Output "::set-output name=SELECTED_COLOR::green"
id: random-color-generator
- name: Get color
run: Write-Output "The selected color is ${{ steps.random-color-generator.outputs.SELECTED_COLOR }}"
以下の表は、ワークフロー内で使えるツールキット関数を示しています。
ツールキット関数 | 等価なワークフローのコマンド |
---|---|
core.addPath | GITHUB_PATH 環境ファイルを使用してアクセス可能 |
core.debug | debug |
core.notice | notice |
core.error | error |
core.endGroup | endgroup |
core.exportVariable | GITHUB_ENV 環境ファイルを使用してアクセス可能 |
core.getInput | INPUT_{NAME} 環境変数を使用してアクセス可能 |
core.getState | STATE_{NAME} 環境変数を使用してアクセス可能 |
core.isDebug | RUNNER_DEBUG 環境変数を使用してアクセス可能 |
出力パラメータの設定
アクションの出力パラメータを設定します。
::set-output name={name}::{value}
あるいは、出力パラメータをアクションのメタデータファイル中で宣言することもできます。 詳細については、「GitHub Actions のメタデータ構文」を参照してく� さい。
環境変数を作成し、ワークフロー コマンドで使用することで、出力パラメーターを設定するための複数行文字列をエスケープできます。 詳しくは、「環境変数の設定」を参照してく� さい。
例: 出力パラメーターの設定
echo "::set-output name=action_fruit::strawberry"
Write-Output "::set-output name=action_fruit::strawberry"
デバッグメッセージの設定
デバッグメッセージをログに出力します。 このコマンドによって設定されたデバッグ メッセージをログで表示するには、ACTIONS_STEP_DEBUG
という名前のシークレットを作成し、値を true
に設定する必要があります。 詳細については、「Enabling debug logging」(デバッグ ログの有効化) を参照してく� さい。
::debug::{message}
例: デバッグ メッセージの設定
echo "::debug::Set the Octocat variable"
Write-Output "::debug::Set the Octocat variable"
通知メッセージの設定
通知メッセージを作成し、ログにそのメッセージを出力します。 このメッセージは注釈を作成します。これにより、リポジトリ内の特定のファイルにメッセージを関連付けることができます。 必要に応じて、メッセージでファイル内の位置を指定できます。
::notice file={name},line={line},endLine={endLine},title={title}::{message}
パラメーター | 値 |
---|---|
title | カスタ� タイトル |
file | ファイル名 |
col | 列番号 (1 から始まる) |
endColumn | 終わりの列番号 |
line | 行番号 (1 から始まる) |
endLine | 終わりの行番号 |
例: 通知メッセージの設定
echo "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Write-Output "::notice file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
警告メッセージの設定
警告メッセージを作成し、ログにそのメッセージを出力します。 このメッセージは注釈を作成します。これにより、リポジトリ内の特定のファイルにメッセージを関連付けることができます。 必要に応じて、メッセージでファイル内の位置を指定できます。
::warning file={name},line={line},endLine={endLine},title={title}::{message}
パラメーター | 値 |
---|---|
title | カスタ� タイトル |
file | ファイル名 |
col | 列番号 (1 から始まる) |
endColumn | 終わりの列番号 |
line | 行番号 (1 から始まる) |
endLine | 終わりの行番号 |
例: 警告メッセージの設定
echo "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Write-Output "::warning file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
エラーメッセージの設定
エラーメッセージを作成し、ログにそのメッセージを出力します。 このメッセージは注釈を作成します。これにより、リポジトリ内の特定のファイルにメッセージを関連付けることができます。 必要に応じて、メッセージでファイル内の位置を指定できます。
::error file={name},line={line},endLine={endLine},title={title}::{message}
パラメーター | 値 |
---|---|
title | カスタ� タイトル |
file | ファイル名 |
col | 列番号 (1 から始まる) |
endColumn | 終わりの列番号 |
line | 行番号 (1 から始まる) |
endLine | 終わりの行番号 |
例: エラー メッセージの設定
echo "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
Write-Output "::error file=app.js,line=1,col=5,endColumn=7::Missing semicolon"
ログの行のグループ化
展開可能なグループをログ中に作成します。 グループを作成するには、group
コマンドを使用して title
を指定します。 ログに出力する group
と endgroup
コマンド間のすべての内容は、ログで展開可能なエントリ内で入れ子になります。
::group::{title}
::endgroup::
例: ログの行のグループ化
jobs:
bash-example:
runs-on: ubuntu-latest
steps:
- name: Group of log lines
run: |
echo "::group::My title"
echo "Inside group"
echo "::endgroup::"
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::"
ログ中での値のマスク
::add-mask::{value}
値をマスクすることにより、文字列または値がログに出力されることを防ぎます。 空白で区切られた、マスクされる各単語は、*
という文字に置き換えられます。 マスクの value
には、環境変数または文字列を使用できます。 値をマスクすると、シークレットとして扱われ、ランナーで編集されます。 たとえば、値をマスクした後は、その値を出力として設定することはできません。
例: 文字列のマスク
ログに "Mona The Octocat"
を出力すると、"***"
と表示されます。
echo "::add-mask::Mona The Octocat"
Write-Output "::add-mask::Mona The Octocat"
警告: シークレットをビルド ログに出力したり、その他のワークフロー コマンド内で使ったりする前に、シークレットを "add-mask" に必ず登録してく� さい。
例: 環境変数のマスク
ログに変数 MY_NAME
または値 "Mona The Octocat"
を出力すると、"Mona The Octocat"
の代わりに "***"
と表示されます。
jobs:
bash-example:
runs-on: ubuntu-latest
env:
MY_NAME: "Mona The Octocat"
steps:
- name: bash-version
run: echo "::add-mask::$MY_NAME"
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"
ワークフローコマンドの停止と開始
ワークフローコマンドの処理を停止します。 この特殊コマンドを使うと、意図せずワークフローコマンドを実行することなくいかなるログも取れます。 たとえば、コメントがあるスクリプト全体を出力するためにログ取得を停止できます。
::stop-commands::{endtoken}
ワークフロー コマンドの処理を停止するには、固有のトークンを stop-commands
に渡します。 ワークフロー コマンドの処理を再開するには、ワークフロー コマンドを停止するために使用したトークンと同じものを渡します。
警告: ランダ� に生成された、実行ごとに固有のトークンを使用するようにしてく� さい。
::{endtoken}::
例: ワークフロー コマンドの停止と開始
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.'
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.'
コマンド出力のエコー
ワークフロー コマンドのエコーを有効または無効にします。 たとえば、ワークフローで set-output
コマンドを使用すると、出力パラメーターが設定されますが、ワークフロー実行のログにはコマンド自体は表示されません。 コマンドのエコーを有効にした� �合、::set-output name={name}::{value}
のようにコマンドがログに表示されます。
::echo::on
::echo::off
コマンドのエコーは既定では無効になっています。 た� し、コマンドの処理中にエラーが発生した� �合は、ワークフロー コマンドがエコーされます。
add-mask
、debug
、warning
、error
コマンドは、出力が既にログにエコーされるようになっているため、エコーをサポートしていません。
ACTIONS_STEP_DEBUG
シークレットを使用してステップのデバッグ ログを有効にすることで、コマンドのエコーをグローバルに有効にすることもできます。 詳しくは、「デバッグ ロギングの有効化」をご覧く� さい。 対照的に、echo
ワークフロー コマンドを使用すると、リポジトリ内のすべてのワークフローに対してコマンドのエコーを有効にするのではなく、より詳細なレベルで有効にすることができます。
例: コマンドのエコーの切り替え
jobs:
workflow-command-job:
runs-on: ubuntu-latest
steps:
- name: toggle workflow command echoing
run: |
echo '::set-output name=action_echo::disabled'
echo '::echo::on'
echo '::set-output name=action_echo::enabled'
echo '::echo::off'
echo '::set-output name=action_echo::disabled'
jobs:
workflow-command-job:
runs-on: windows-latest
steps:
- name: toggle workflow command echoing
run: |
write-output "::set-output name=action_echo::disabled"
write-output "::echo::on"
write-output "::set-output name=action_echo::enabled"
write-output "::echo::off"
write-output "::set-output name=action_echo::disabled"
上記の例では、次の行がログに出力されます。
::set-output name=action_echo::enabled
::echo::off
ログには 2 番目の set-output
と echo
ワークフロー コマンドのみが含まれています。これは、それらのコマンドが実行されたときにのみコマンドのエコーが有効になったからです。 出力パラメーターは、常にエコーされるとは限りませんが、すべての� �合において設定されます。
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 エンコーディングを使用する必要があります。 複数のコマンドを、改行で区切って同じファイルに書き込むことができます。
次の例のほどんどのコマンドでは、エコー文字列に二重引用符を使います。これにより、シェル変数名に対して $
などの文字の補間が試行されます。 引用符で囲まれた文字列でリテラル値を常に使用するには、代わりに単一引用符を使用できます。
注: PowerShell バージョン 5.1 以下 (shell: powershell
) では UTF-8 が既定で使用されないため、UTF-8 エンコードを指定する必要があります。 次に例を示します。
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 が既定で使用されます。 次に例を示します。
jobs:
powershell-core-example:
runs-on: windows-latest
steps:
- shell: pwsh
run: |
"mypath" >> $env:GITHUB_PATH
環境変数の設定
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
環境ファイルに書き込むことで、ワークフロー ジョブの後続のステップで環境変数が利用できるようになります。 環境変数を作成または更新するステップは、新しい値にアクセスできませんが、ジョブにおける後続のすべてのステップはアクセスできます。 環境変数の名前では、大文字と小文字が区別され、句読点を含めることができます。 詳しくは、「環境変数」をご覧く� さい。
例
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'
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'
複数行の文字列
複数行の文字列の� �合、次の構文で区切り文字を使用できます。
{name}<<{delimiter}
{value}
{delimiter}
警告: ランダ� に生成された、実行ごとに固有の区切り記号を使用するようにしてく� さい。 詳細については、「スクリプト インジェクションのリスクを理解する」を参照してく� さい。
例
この例では、区切り文字として EOF
を使用し、JSON_RESPONSE
環境変数を curl
の応答の値に設定します。
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
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
システ� パスの追�
システ� の PATH
変数の先� �にディレクトリを追� し、自動的に現在のジョブにおける後続のすべてのアクションで利用できるようにします。現在実行中のアクションは、更新されたパス変数にアクセスできません。 ジョブに現在定義されているパスを確認するには、ステップまたはアクションで echo "$PATH"
を使うことができます。
echo "{path}" >> $GITHUB_PATH
"{path}" >> $env:GITHUB_PATH
例
この例では、ユーザーの $HOME/.local/bin
ディレクトリを PATH
に追� する方法を示しています。
echo "$HOME/.local/bin" >> $GITHUB_PATH
この例では、ユーザーの $env:HOMEPATH/.local/bin
ディレクトリを PATH
に追� する方法を示しています。
"$env:HOMEPATH/.local/bin" >> $env:GITHUB_PATH