注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
GitHub ActionsのYAML構文について
すべてのアクションにメタデータ ファイルが必要です。 メタデータ ファイル名は、action.yml
または action.yaml
である必要があります。 メタデータ ファイル内のデータにより、アクションの入力、出力、実行の構成を定義されます。
アクションのメタデータファイルはYAML構文を使います。 YAML を初めて使用する� �合は、「5 分で学ぶ YAML」を参照してく� さい。
name
必� � アクションの名前。 GitHub の [アクション] タブには name
が表示され、各ジョブのアクションを視覚的に特定するのに役立ちます。
author
省略可能 アクションの作成者の名前。
description
必� � アクションの簡単な説明。
inputs
省略可能 入力パラメーターでは、実行時にアクションで使用するデータを指定できます。 GitHubは、inputsパラメータを環境変数として保存します。 大文字が使われているInputsのidは、実行時に小文字に変換されます。 inputsのidには小文字を使うことをおすすめします。
例: 入力の指定
この例では、numOctocatsとoctocatEyeColorという 2つの入力を設定しています。 入力のnumOctocatsは必� �ではなく、デフォルトの値は'1'になっています。 入力のoctocatEyeColorは必� �であり、デフォルト値を持ちません。 このアクションを使用するワークフロー ファイルでは、with
キーワードを使って octocatEyeColor の入力値を設定する必要があります。 with
構文の詳細については、「GitHub Actions のワークフロー構文」を参照してく� さい。
inputs:
numOctocats:
description: 'Number of Octocats'
required: false
default: '1'
octocatEyeColor:
description: 'Eye color of the Octocats'
required: true
ワークフロー ファイル内で入力を指定するか、既定の入力値を使用すると、GitHub により、その入力に対して、INPUT_<VARIABLE_NAME>
という名前の環境変数が作成されます。 作成された環境変数では、入力名を大文字に変換し、空白を _
文字に置き換えます。
アクションが composite を使用して書き込まれている� �合は、自動的に INPUT_<VARIABLE_NAME>
が取得されません。 変換されない� �合は、これらの入力を手動で変更できます。
Docker コンテナー アクションの環境変数にアクセスするには、アクション メタデータ ファイルで args
キーワードを使用して入力を渡す必要があります。 Docker コンテナー アクションのアクション メタデータ ファイルについて詳しくは、「Docker コンテナー アクションの作成」を参照してく� さい。
たとえば、ワークフローで numOctocats
および octocatEyeColor
入力が定義されている� �合は、アクション コードで、INPUT_NUMOCTOCATS
および INPUT_OCTOCATEYECOLOR
環境変数を使用して入力の値を読み取ることができます。
inputs.<input_id>
必� � 入力に関連付ける string
識別子。 <input_id>
の値は、入力のメタデータのマップです。 <input_id>
は、inputs
オブジェクト内の一意識別子である必要があります。 <input_id>
は文字または _
で始まり、英数字、-
、あるいは _
のみを含める必要があります。
inputs.<input_id>.description
必� � 入力パラメーターの string
の説明。
inputs.<input_id>.required
省略可能 アクションに入力パラメーターが必要かどうかを示す boolean
。 パラメーターが必要な� �合は、true
に設定します。
inputs.<input_id>.default
省略可能 既定値を表す string
。 デフォルト値は、入力パラメーターがワークフローファイルで指定されなかった� �合に使われます。
inputs.<input_id>.deprecationMessage
省略可能 入力パラメーターが使用されている� �合、この string
は警告メッセージとしてログに記録されます。 この警告で入力が非推奨であることをユーザに通知し、その他の方法を知らせることができます。
Docker コンテナーと JavaScript アクションの outputs
省略可能 出力パラメーターを使用すると、アクションで設定されるデータを宣言できます。 ワークフローで後に実行されるアクションは、先行して実行されたアクションが設定した出力データを利用できます。 たとえば、2つの入力を� 算(x + y = z)するアクションがあれば、そのアクションは他のアクションが入力として利用できる合計値(z)を出力できます。
出力は Unicode 文字列であり、最大 1 MB となります。 ワークフロー実行内のすべての出力の合計は、最大 50 MB です。
メタデータファイル中でアクション内の出力を宣言しなくても、出力を設定してワークフロー中で利用することはできます。 アクションでの出力の設定については詳しくは、「GitHub Actions のワークフロー コマンド」を参照してく� さい。
例: Docker コンテナーと JavaScript アクションの出力の宣言
outputs:
sum: # id of the output
description: 'The sum of the inputs'
outputs.<output_id>
必� � 出力に関連付ける string
識別子。 <output_id>
の値は、出力のメタデータのマップです。 <output_id>
は、outputs
オブジェクト内の一意識別子である必要があります。 <output_id>
は文字または _
で始まり、英数字、-
、あるいは _
のみを含める必要があります。
outputs.<output_id>.description
必� � 出力パラメーターの string
の説明。
複合アクションの outputs
省略可能 outputs
では outputs.<output_id>
および outputs.<output_id>.description
と同じパラメーターが使用されます (「Docker コンテナーと JavaScript アクションの outputs
」を参照) が、value
トークンも含まれます。
出力は Unicode 文字列であり、最大 1 MB となります。 ワークフロー実行内のすべての出力の合計は、最大 50 MB です。
例: 複合アクションの出力の宣言
outputs:
random-number:
description: "Random number"
value: ${{ steps.random-number-generator.outputs.random-id }}
runs:
using: "composite"
steps:
- id: random-number-generator
run: echo "::set-output name=random-id::$(echo $RANDOM)"
shell: bash
outputs.<output_id>.value
必� � 出力パラメーターがマップされる値。 これは、string
またはコンテキスト付きの式に設定できます。 たとえば、steps
コンテキストを使用して、出力の value
をステップの出力値に設定できます。
コンテキスト構文の使用方法について詳しくは、「コンテキスト」を参照してく� さい。
runs
必� � これが JavaScript アクション、複合アクション、Docker コンテナー アクションのいずれであるか、およびアクションの実行方法を指定します。
JavaScript のアクションの runs
必� � アクションのコードへのパスと、コードの実行に使用されるランタイ� を構成します。
例: Node.js v12 の使用
runs:
using: 'node12'
main: 'main.js'
runs.using
必� � main
で指定されたコードを実行するために使用されるランタイ� 。
- Node.js v12 では
node12
を使用。 ではnode16
を使用。
runs.main
必� � アクション コードを含むファイル。 using
で指定されたランタイ� でこのファイルが実行されます。
runs.pre
省略可能 main:
アクションが開始される前に、ジョブの開始時にスクリプトを実行できます。 たとえば、pre:
を使って必要なセットアップ スクリプトを実行できます。 using
構文で指定されたランタイ� によりこのファイルが実行されます。 pre:
アクションは常に既定で実行されますが、runs.pre-if
を使用してこれをオーバーライドすることはできます。
この例では、pre:
アクションによって setup.js
というスクリプトが実行されます。
runs:
using: 'node12'
pre: 'setup.js'
main: 'index.js'
post: 'cleanup.js'
runs.pre-if
省略可能 pre:
アクションの実行条件を定義できます。 pre:
アクションは、pre-if
内の条件が満たされた� �合にのみ実行されます。 設定されていない� �合、pre-if
は既定で always()
に設定されます。 pre-if
では、ステータス チェック関数は、アクション自体の状態ではなく、ジョブの状態に対して評価されます。
ま� ステップが実行されていないので、step
コンテキストは利用できないことに注意してく� さい。
以下の例では、cleanup.js
は Linux ベースのランナーでのみ実行されます。
pre: 'cleanup.js'
pre-if: runner.os == 'linux'
runs.post
省略可能 main:
アクションが完了したら、ジョブの終了時にスクリプトを実行できます。 たとえば、post:
を使って特定のプロセスを終了させたり、不要なファイルを削除したりできます。 using
構文で指定されたランタイ� によりこのファイルが実行されます。
この例では、post:
アクションによって cleanup.js
というスクリプトが実行されます。
runs:
using: 'node12'
main: 'index.js'
post: 'cleanup.js'
post:
アクションは常に既定で実行されますが、post-if
を使用してこれをオーバーライドすることはできます。
runs.post-if
省略可能 post:
アクションの実行条件を定義できます。 post:
アクションは、post-if
内の条件が満たされた� �合にのみ実行されます。 設定されていない� �合、post-if
は既定で always()
に設定されます。 post-if
では、ステータス チェック関数は、アクション自体の状態ではなく、ジョブの状態に対して評価されます。
たとえば、この cleanup.js
は Linux ベースのランナーでのみ実行されます。
post: 'cleanup.js'
post-if: runner.os == 'linux'
複合アクションの runs
必� � 複合アクションへのパスを構成します。
runs.using
必� � この値を 'composite'
に設定する必要があります。
runs.steps
必� � このアクションで実行する予定のステップ。 これらは、run
ステップまたは uses
ステップにすることができます。
runs.steps[*].run
省略可能 実行するコマンド。 これは、インラインでも、アクション リポジトリ内のスクリプトでもかまいません。
runs:
using: "composite"
steps:
- run: ${{ github.action_path }}/test/script.sh
shell: bash
$GITHUB_ACTION_PATH
を使用することもできます。
runs:
using: "composite"
steps:
- run: $GITHUB_ACTION_PATH/script.sh
shell: bash
詳細については、github context
を参照してく� さい。
runs.steps[*].shell
省略可能 コマンドを実行するシェル。 ここに一覧表示されているシェルのいずれかを使用できます。 run
が設定されている� �合は必� �です。
runs.steps[*].name
省略可能 複合ステップの名前。
runs.steps[*].id
省略可能 ステップの一意識別子。 id
を使って、コンテキストのステップを参照することができます。 詳細については、「コンテキスト」を参照してく� さい。
runs.steps[*].env
省略可能 そのステップのみの環境変数の map
を設定します。 ワークフローに� �納されている環境変数を変更する� �合は、複合ステップで echo "{name}={value}" >> $GITHUB_ENV
を使用します。
runs.steps[*].working-directory
省略可能 コマンドが実行される作業ディレクトリを指定します。
runs.steps[*].uses
省略可能 ジョブでステップの一部として実行されるアクションを選択します。 アクションとは、再利用可能なコードの単位です。 ワークフローと同じリポジトリ、パブリック リポジトリ、または公開されている Docker コンテナー イメージで定義されているアクションを使用できます。
Git ref、SHA、またはDockerタグ番号を指定して、使用しているアクションのバージョンを含めることを強く推奨します。 バージョンを指定しないと、アクションのオーナーがアップデートを公開したときに、ワークフローが中断したり、予期せぬ動作をしたりすることがあります。
- リリースされたアクションバージョンのコミットSHAを使用するのが、安定性とセキュリティのうえで最も安全です。
- 特定のメジャーアクションバージョンを使用すると、互換性を維持したまま重要な修正とセキュリティパッチを受け取ることができます。 ワークフローが引き続き動作することも保証できます。
- アクションのデフォルトブランチを使用すると便利なこともありますが、別のユーザが� �壊的変更を� えた新しいメジャーバージョンをリリースすると、ワークフローが動作しなくなる� �合があります。
一部のアクションでは、with
キーワードを使用して設定する必要がある入力が必要です。 必要な入力を判断するには、アクションのREADMEファイルをお読みく� さい。
runs:
using: "composite"
steps:
# Reference a specific commit
- uses: actions/checkout@a81bbbf8298c0fa03ea29cdc473d45769f953675
# Reference the major version of a release
- uses: actions/checkout@v2
# Reference a specific version
- uses: actions/checkout@v2.2.0
# Reference a branch
- uses: actions/checkout@main
# References a subdirectory in a public GitHub repository at a specific branch, ref, or SHA
- uses: actions/aws/ec2@main
# References a local action
- uses: ./.github/actions/my-action
# References a docker public registry action
- uses: docker://gcr.io/cloud-builders/gradle
# Reference a docker image published on docker hub
- uses: docker://alpine:3.8
runs.steps[*].with
省略可能 アクションによって定義される入力パラメーターの map
。 各入力パラメータはキー/値ペアです。 詳しくは、「例: 入力の指定」をご覧く� さい。
runs:
using: "composite"
steps:
- name: My first step
uses: actions/hello_world@main
with:
first_name: Mona
middle_name: The
last_name: Octocat
Docker コンテナー アクションの runs
必� � Docker コンテナー アクションに使用されるイメージを構成します。
例: リポジトリでの Dockerfile の使用
runs:
using: 'docker'
image: 'Dockerfile'
例: パブリック Docker レジストリ コンテナーの使用
runs:
using: 'docker'
image: 'docker://debian:stretch-slim'
runs.using
必� � この値を 'docker'
に設定する必要があります。
runs.pre-entrypoint
省略可能 entrypoint
アクションが開始される前にスクリプトを実行できます。 たとえば、pre-entrypoint:
を使って必要なセットアップ スクリプトを実行できます。 GitHub Actions では docker run
を使ってこのアクションを起動し、同じベース イメージを使用する新しいコンテナー内でスクリプトを実行します。 つまり、ランタイ� の状態はメインの entrypoint
コンテナーとは異なり、必要な状態はワークスペース、HOME
で、または STATE_
変数としてアクセスされる必要があります。 pre-entrypoint:
アクションは常に既定で実行されますが、runs.pre-if
を使用してこれをオーバーライドすることはできます。
using
構文で指定されたランタイ� によりこのファイルが実行されます。
この例では、pre-entrypoint:
アクションによって setup.sh
というスクリプトが実行されます。
runs:
using: 'docker'
image: 'Dockerfile'
args:
- 'bzz'
pre-entrypoint: 'setup.sh'
entrypoint: 'main.sh'
runs.image
必� � アクションを実行するコンテナーとして使用する Docker イメージ。 値は、Docker のベース イメージ名、ご自分のリポジトリ内のローカル Dockerfile
、または Docker Hub あるいは別のレジストリ内のパブリック イメージにすることができます。 ご自分のリポジトリにローカルな Dockerfile
を参照するには、ファイルに Dockerfile
という名前を付ける必要があり、アクション メタデータ ファイルに対する相対パスを使用する必要があります。 docker
アプリケーションによってこのファイルが実行されます。
runs.env
省略可能 コンテナー環境で設定する環境変数のキー/値のマップを指定します。
runs.entrypoint
省略可能 Dockerfile
内の Docker の ENTRYPOINT
をオーバーライドするか、ま� 指定されていない� �合は設定します。 Dockerfile
で ENTRYPOINT
が指定されていない� �合や、ENTRYPOINT
命令をオーバーライドする� �合は entrypoint
を使用します。 entrypoint
を省略すると、Docker の ENTRYPOINT
命令で指定したコマンドが実行されます。 Docker の ENTRYPOINT
命令には、shell 形式と exec 形式があります。 Docker の ENTRYPOINT
ドキュメントでは、ENTRYPOINT
命令の exec 形式を使用することが推奨されています。
entrypoint
の実行方法について詳しくは、「GitHub Actions のための Dockerfile サポート」を参照してく� さい。
runs.post-entrypoint
省略可能 runs.entrypoint
アクションが完了したら、クリーンアップ スクリプトを実行できます。 GitHub Actions では docker run
を使用して、このアクションを起動します。 GitHub Actions ではスクリプトを同じベース イメージを使って新しいコンテナー内で実行するため、ランタイ� の状態はメインの entrypoint
コンテナーとは異なります。 ワークスペース、HOME
で、または STATE_
変数として必要な任意の状態にアクセスできます。 post-entrypoint:
アクションは常に既定で実行されますが、runs.post-if
を使用してこれをオーバーライドすることはできます。
runs:
using: 'docker'
image: 'Dockerfile'
args:
- 'bzz'
entrypoint: 'main.sh'
post-entrypoint: 'cleanup.sh'
runs.args
省略可能 Docker コンテナーの入力を定義する文字列の配列。 入力には、ハードコードされた文字列を含めることができます。 GitHub により、コンテナーの起動時に args
がコンテナーのENTRYPOINT
に渡されます。
args
は、Dockerfile
内の CMD
命令の代わりに使用されます。 ご自分の Dockerfile
で CMD
を使用する� �合は、以下の優先� �のガイドラインを使用してく� さい。
- アクションの README 中で必� �の引数をドキュメント化し、
CMD
命令から除外します。 args
を指定せずにアクションを利用できるよう、既定値を使用します。- アクションが
--help
フラグやそれに類するものを備えているなら、アクションを自己ドキュメント化するためにそれを利用します。
環境変数をアクションに渡す必要がある� �合は、変数置換を行えるようアクションがコマンドシェルで実行されていることを確認してく� さい。 たとえば、entrypoint
属性が "sh -c"
に設定されている� �合は、args
がコマンド シェルで実行されます。 あるいは、Dockerfile
で ENTRYPOINT
を使用して同じコマンド ("sh -c"
) を実行する� �合は、args
がコマンド シェルで実行されます。
GitHub Actions での CMD
命令の使用について詳しくは、「GitHub Actions のための Dockerfile サポート」を参照してく� さい。
例: Docker コンテナーの引数の定義
runs:
using: 'docker'
image: 'Dockerfile'
args:
- ${{ inputs.greeting }}
- 'foo'
- 'bar'
branding
省略可能: アクションをパーソナライズして見分けられるようにするために、カラーと Feather アイコンを使ってバッジを作成することができます。 バッジは、GitHub Marketplace のアクション名の横に表示されます。
例: アクションのブランド化の構成
branding:
icon: 'award'
color: 'green'
branding.color
バッジの背景カラー。 white
、yellow
、blue
、green
、orange
、red
、purple
、gray-dark
のいずれかにすることができます。
branding.icon
使用する v4.28.0 Feather アイコンの名前。 ブランド アイコンと以下のものは省略されます。
コーヒー | 列 | divide-circle | divide-square |
divide | frown | hexagon | key |
meh | mouse-pointer | smile | ツール (tool) |
x-octagon |
現在サポートされているすべてのアイコンの完全なリストを以下に示します。
activity | airplay | alert-circle | alert-octagon |
alert-triangle | align-center | align-justify | align-left |
align-right | アンカー | aperture | アーカイブ |
arrow-down-circle | arrow-down-left | arrow-down-right | arrow-down |
arrow-left-circle | arrow-left | arrow-right-circle | arrow-right |
arrow-up-circle | arrow-up-left | arrow-up-right | arrow-up |
at-sign | award | bar-chart-2 | bar-chart |
battery-charging | battery | battery | ベル |
Bluetooth | 太字 | book-open | book |
ブックマーク (bookmark) | box | briefcase | カレンダー |
camera-off | カメラ | キャスト | check-circle |
check-square | チェック | chevron-down | chevron-left |
chevron-right | chevron-up | chevrons-down | chevrons-left |
chevrons-right | chevrons-up | circle | クリップボード |
clock | cloud-drizzle | cloud-lightning | cloud-off |
cloud-rain | cloud-snow | cloud | code |
command | compass | copy | corner-down-left |
corner-down-right | corner-left-down | corner-left-down | corner-right-down |
corner-right-up | corner-up-left | corner-up-right | cpu |
credit-card | crop | crosshair | database |
delete | disc | dollar-sign | download-cloud |
download | droplet | edit-2 | edit-3 |
編集 | external-link | eye-off | eye |
fast-forward | feather | file-minus | file-plus |
file-text | file | film | filter |
flag | folder-minus | folder-plus | folder |
gift | git-branch | git-commit | git-merge |
git-pull-request | globe | grid | hard-drive |
hash | headphones | ハート | help-circle |
home | image | inbox | info |
斜体 | レイヤー | レイアウト | life-buoy |
link-2 | link | list | loader |
lock | log-in | log-out | |
map-pin | map | maximize-2 | maximize |
メニュー | message-circle | message-square | mic-off |
mic | minimize-2 | minimize | minus-circle |
minus-square | minus | 監視 | moon |
more-horizontal | more-vertical | 移動 | music |
navigation-2 | ナビゲーション | octagon | パッケージ |
paperclip | pause-circle | pause | パーセント |
phone-call | phone-forwarded | phone-incoming | phone-missed |
phone-off | phone-outgoing | phone | pie-chart |
play-circle | play | plus-circle | plus-square |
plus | power | printer | |
radio | refresh-ccw | refresh-cw | repeat |
rewind | rotate-ccw | rotate-cw | rss |
[保存] | scissors | 検索 | [Send] |
server | settings | share-2 | 共有 |
shield-off | shield | shopping-bag | shopping-cart |
シャッフル | サイド バー●さいどばー○ | skip-back | skip-forward |
slash | スライダー | smartphone | スピーカー |
square | 星 | stop-circle | sun |
sunrise | sunset | タブレット | タグ |
ターゲット (target) | terminal | thermometer | thumbs-down |
thumbs-up | toggle-left | toggle-right | trash-2 |
trash | trending-down | trending-up | triangle |
truck | tv | type | 傘 |
下線 | ロック解除 | upload-cloud | upload |
user-check | user-minus | user-plus | user-x |
ユーザー | users | video-off | video |
voicemail | volume-1 | volume-2 | volume-x |
ボリュー� | watch | wifi-off | wifi |
wind | x-circle | x-square | x |
zap-off | zap | zoom-in | zoom-out |