GitHub ActionsのYAML構文について
すべてのアクションにメタデータ ファイルが必要です。 メタデータ ファイル名は、action.yml
または action.yaml
である必要があります。 メタデータ ファイル内のデータにより、アクションの入力、出力、実行の構成を定義されます。
アクションのメタデータファイルはYAML構文を使います。 YAML を初めて使用する場合は、「5 分で学ぶ YAML」を参照してください。
name
必須 アクションの名前。 GitHub の [アクション] タブには name
が表示され、各ジョブのアクションを視覚的に特定するのに役立ちます。
author
省略可能 アクションの作成者の名前。
description
必須 アクションの簡単な説明。
inputs
省略可能 入力パラメーターでは、実行時にアクションで使用するデータを指定できます。 GitHubは、inputsパラメータを環境変数として保存します。 大文字が使われているInputsのidは、実行時に小文字に変換されます。 inputsの id には小文字を使うことをおすすめします。
例: 入力の指定
この例では、num-octocats
と octocat-eye-color
という 2 つの入力を構成しています。 num-octocats
入力は必須ではなく、既定の値は 1
になります。 octocat-eye-color
は必須で、既定値はありません。
注: ワークフローの実行を自動的にトリガーするイベントに入力が指定されていない場合、required: true
を使用するワークフローでは自動的にエラーが返されません。 ワークフロー ファイルで required: true
を設定し、workflow_dispatch
を使用してワークフローを手動で実行する場合は、GitHub.com に入力を指定する必要があります。 詳しくは、「ワークフローをトリガーするイベント」を参照してください。
このアクションが使用されているワークフロー ファイルでは、with
キーワードを使って、octocat-eye-color
の入力値を設定できます。 with
の構文について詳しくは、「ギットハブ アクション のワークフロー構文」をご覧ください。
inputs:
num-octocats:
description: 'Number of Octocats'
required: false
default: '1'
octocat-eye-color:
description: 'Eye color of the Octocats'
required: true
ワークフロー ファイル内で入力を指定するか、既定の入力値を使用すると、GitHub により、その入力に対して、INPUT_<VARIABLE_NAME>
という名前の環境変数が作成されます。 作成された環境変数では、入力名を大文字に変換し、空白を _
文字に置き換えます。
アクションが composite を使用して書き込まれている場合は、自動的に INPUT_<VARIABLE_NAME>
が取得されません。 変換されない場合は、これらの入力を手動で変更できます。
Docker コンテナー アクションの環境変数にアクセスするには、アクション メタデータ ファイルで args
キーワードを使用して入力を渡す必要があります。 Docker コンテナー アクションのアクション メタデータ ファイルについて詳しくは、「Docker コンテナーのアクションを作成する」をご覧ください。
たとえば、ワークフローで num-octocats
および octocat-eye-color
入力が定義されている場合は、アクション コードで、INPUT_NUM-OCTOCATS
および INPUT_OCTOCAT-EYE-COLOR
環境変数を使用して入力の値を読み取ることができます。
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 "random-id=$(echo $RANDOM)" >> $GITHUB_OUTPUT
shell: bash
outputs.<output_id>.value
必須 出力パラメーターがマップされる値。 これは、string
またはコンテキスト付きの式に設定できます。 たとえば、steps
コンテキストを使用して、出力の value
をステップの出力値に設定できます。
コンテキスト構文の使い方について詳しくは、「コンテキスト」をご覧ください。
runs
必須 これが JavaScript アクション、複合アクション、Docker コンテナー アクションのいずれであるか、およびアクションの実行方法を指定します。
JavaScript のアクションの runs
必須 アクションのコードへのパスと、コードの実行に使用されるランタイムを構成します。
例: Node.js v20 を使用する
runs:
using: 'node20'
main: 'main.js'
JavaScript のアクションの runs.using
必須 main
で指定されたコードを実行するために使用されるランタイム。
- Node.js v20 では
node20
を使用する。
runs.main
必須 アクション コードを含むファイル。 using
で指定されたランタイムでこのファイルが実行されます。
runs.pre
省略可能 main:
アクションが開始される前に、ジョブの開始時にスクリプトを実行できます。 たとえば、pre:
を使って必要なセットアップ スクリプトを実行できます。 using
構文で指定されたランタイムによりこのファイルが実行されます。 pre:
アクションは常に既定で実行されますが、runs.pre-if
を使用してこれをオーバーライドすることはできます。
この例では、pre:
アクションによって setup.js
というスクリプトが実行されます。
runs:
using: 'node20'
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: 'node20'
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
詳細については、「コンテキスト」を参照してください。
runs.steps[*].shell
省略可能 コマンドを実行するシェル。 「ギットハブ アクション のワークフロー構文」に一覧表示されているシェルのいずれかを使用できます。 run
が設定されている場合は必須です。
runs.steps[*].if
省略可能 if
条件文を使って、条件が満たされなければ、ステップを実行しないようにすることができます。 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。
if
条件の中で式を使う際には、式構文 ${{ }}
を省略できます。これは、GitHub Actions が if
条件を式として自動的に評価するためです。 ただし、このルールはどこでも適用されるわけではありません。
!
は YAML 形式で予約された表記であるため、式が !
で始まる場合は、${{ }}
構文の式を使用するか、''
、""
、または ()
でエスケープする必要があります。
式構文 ${{ }}
を使用すると、内容が文字列に変わり、文字列は真値です。 たとえば、if: true && ${{ false }}
は true
に評価されます。 詳しくは、「式」をご覧ください。
例: コンテキストの使用
このステップは、イベントの種類が pull_request
で、イベント アクションが unassigned
である場合にのみ実行されます。
steps:
- run: echo This event is a pull request that had an assignee removed.
if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
例: ステータス チェック関数の使用
複合アクションの前のステップが失敗した場合にのみ、my backup step
が実行されます。 詳しくは、「式」を参照してください。
steps:
- name: My first step
uses: octo-org/action-name@main
- name: My backup step
if: ${{ failure() }}
uses: actions/heroku@1.0.0
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@8f4b7f84864484a7bf31766abe9204da3cbe65b3
# Reference the major version of a release
- uses: actions/checkout@v4
# Reference a specific version
- uses: actions/checkout@v4.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'
Docker コンテナー アクションの 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