GitHub Actions のメタデータ構文

GitHub ActionsのYAML構文について

すべてのアクションにメタデータファイルが必要です。メタデータファイル名は、action.yml または action.yaml である必要があります。推奨される形式は action.yml です。メタデータファイル内のデータにより、アクションの入力、出力、実行の構成を定義されます。

アクションのメタデータファイルはYAML構文を使います。 YAML を初めて使用する場合は、「Learn YAML in five minutes」(5 分で学ぶ YAML) を参照してください。

`name`

必須アクションの名前。 GitHub の [アクション] タブには name が表示され、各ジョブのアクションを視覚的に特定するのに役立ちます。

`author`

省略可能 アクションの作成者の名前。

`description`

必須アクションの簡単な説明。

`inputs`

省略可能 入力パラメーターでは、実行時にアクションで使用するデータを指定できます。 GitHubは、inputsパラメータを環境変数として保存します。 inputsの id には小文字を使うことをおすすめします。

例: 入力の指定

この例では、num-octocats と octocat-eye-color という 2 つの入力を構成しています。 num-octocats 入力は必須ではなく、既定の値は 1 になります。 octocat-eye-color は必須で、既定値はありません。

Note

入力が指定されていない場合、required: true を使用するアクションは自動的にエラーを返しません。

このアクションが使用されているワークフローファイルでは、with キーワードを使って、octocat-eye-color の入力値を設定できます。 with 構文の詳細については、「GitHub Actions　のワークフロー構文」を参照してください。

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> が取得されません。複合アクションを使用すると、inputs ワークフロー実行に関するコンテキスト情報へのアクセスを使用してアクション入力にアクセスできます。

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`

省略可能 コマンドを実行するシェル。「GitHub Actions　のワークフロー構文」に記載されているシェルのいずれかを使用できます。 run が設定されている場合は必須です。

`runs.steps[*].if`

省略可能 if 条件文を使って、条件が満たされなければ、ステップを実行しないようにすることができます。条件文を作成するには、サポートされている任意のコンテキストや式が使えます。

if 条件の中で式を使う際には、任意で式構文 ${{ }} を省略できます。これは、GitHub Actions が if 条件を式として自動的に評価するためです。ただし、この例外はどこでも適用されるわけではありません。

! は YAML 形式で予約された表記であるため、必ず${{ }} 構文の式を使用するか、式が ! で始まる場合は ''、""、または () でエスケープする必要があります。次に例を示します。

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

詳細については、「ワークフローとアクションで式を評価する」を参照してください。

例: コンテキストの使用

このステップは、イベントの種類が 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、black、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
mail
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
pocket
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
日没
テーブル
タブレット
タグ
ターゲット (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

メタデータファイル名を変更する

アクションのメタデータファイルは両方の YAML 形式をサポートしていますが、リリース間でメタデータファイル名を変更 (action.yml から action.yaml またはその逆) すると、GitHub Marketplace に公開されている以前のリリースバージョンに影響します。ファイル名を変更すると、以前のファイル名に関連付けられているすべてのリリースバージョンが GitHub Marketplace に表示されなくなります。以前のリリースバージョンには、ソースリポジトリを介してユーザーは引き続きアクセスできます。

新しいバージョンのアクションをリリースすると、メタデータファイル名の変更後にリリースされたバージョンのみが GitHub Marketplace タグを持ち、GitHub Marketplace に表示されます

GitHub Actions のメタデータ構文

この記事の内容