GitHub Actions のメタデータ構文

注: 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	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	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

GitHub Actions のメタデータ構文

この記事では、次の� �目が扱われます。

GitHub ActionsのYAML構文について

name

author

description

inputs

例: 入力の指定

inputs.<input_id>

inputs.<input_id>.description

inputs.<input_id>.required

inputs.<input_id>.default

inputs.<input_id>.deprecationMessage

Docker コンテナーと JavaScript アクションの outputs

例: Docker コンテナーと JavaScript アクションの出力の宣言

outputs.<output_id>

outputs.<output_id>.description

複合アクションの outputs

例: 複合アクションの出力の宣言

outputs.<output_id>.value

runs

JavaScript のアクションの runs

例: Node.js v12 の使用

runs.using

runs.main

runs.pre

runs.pre-if

runs.post

runs.post-if

複合アクションの runs

runs.using

runs.steps

runs.steps[*].run

runs.steps[*].shell

runs.steps[*].name

runs.steps[*].id

runs.steps[*].env

runs.steps[*].working-directory

runs.steps[*].uses

runs.steps[*].with

Docker コンテナー アクションの runs

例: リポジトリでの Dockerfile の使用

例: パブリック Docker レジストリ コンテナーの使用

runs.using

runs.pre-entrypoint

runs.image

runs.env

runs.entrypoint

runs.post-entrypoint

runs.args

例: Docker コンテナーの引数の定義

branding

例: アクションのブランド化の構成

branding.color

branding.icon

`name`

`author`

`description`

`inputs`

`inputs.<input_id>`

`inputs.<input_id>.description`

`inputs.<input_id>.required`

`inputs.<input_id>.default`

`inputs.<input_id>.deprecationMessage`

Docker コンテナーと JavaScript アクションの `outputs`

`outputs.<output_id>`

`outputs.<output_id>.description`

複合アクションの `outputs`

`outputs.<output_id>.value`

`runs`

JavaScript のアクションの `runs`

`runs.using`

`runs.main`

`runs.pre`

`runs.pre-if`

`runs.post`

`runs.post-if`

複合アクションの `runs`

`runs.using`

`runs.steps`

`runs.steps[*].run`

`runs.steps[*].shell`

`runs.steps[*].name`

`runs.steps[*].id`

`runs.steps[*].env`

`runs.steps[*].working-directory`

`runs.steps[*].uses`

`runs.steps[*].with`

Docker コンテナーアクションの `runs`

例: パブリック Docker レジストリコンテナーの使用

`runs.using`

`runs.pre-entrypoint`

`runs.image`

`runs.env`

`runs.entrypoint`

`runs.post-entrypoint`

`runs.args`

`branding`

`branding.color`

`branding.icon`