GitHub Actionsのメタデータ構文

GitHub ActionsのYAML構文について

Docker及びJavaScriptアクションにはメタデータファイルが必要です。 このメタデータのファイル名はaction.ymlもしくはaction.yamlでなければなりません。 メタデータファイル中のデータは、アクションの入力、出力、メインエントリポイントを定義します。

アクションのメタデータファイルはYAML構文を使います。 YAMLについて詳しくない場合は、「Learn YAML in five minutes (5分で学ぶYAML)」をお読みください。

name

必須アクションの名前。 GitHubはnameをActionsタブに表示して、それぞれのジョブのアクションを見て区別しやすくします。

author

オプション アクションの作者の名前。

description

必須 アクションの短い説明。

inputs

オプション 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>という名前の環境変数を生成します。 生成される環境変数では、入力の名前を大文字にして、空白を_に変換します。

たとえば、ワークフローで numOctocats および octocatEyeColor 入力が定義されている場合、アクションコードは INPUT_NUMOCTOCATS および INPUT_OCTOCATEYECOLOR 環境変数を使用して入力の値を読み取ることができます。

inputs.<input_id>

必須 文字列型の識別子で、入力と結びつけられます。 <input_id>の値は、入力のメタデータのマップです。 <input_id>は、inputsオブジェクト内でユニークな識別子でなければなりません。 <input_id>は、文字あるいは_で始める必要があり、英数字、-、_しか使用できません。

inputs.<input_id>.description

必須 入力パラメーターの文字列での説明。

inputs.<input_id>.required

必須 この入力パラメーターがアクションに必須かどうかを示す論理値。 パラメーターが必須の場合はtrueに設定してください。

inputs.<input_id>.default

オプション デフォルト値を示す文字列。 デフォルト値は、入力パラメーターがワークフローファイルで指定されたなかった場合に使われます。

inputs.<input_id>.deprecationMessage

オプション 入力パラメータが使用されている場合、この string は警告メッセージとしてログに記録されます。 この警告で入力が非推奨であることをユーザに通知し、その他の方法を知らせることができます。

outputs

オプション アクションが設定するデータを宣言できる出力パラメータ。 ワークフローで後に実行されるアクションは、先行して実行されたアクションが設定した出力データを利用できます。 たとえば、2つの入力を加算(x + y = z)するアクションがあれば、そのアクションは他のアクションが入力として利用できる合計値(z)を出力できます。

メタデータファイル中でアクション内の出力を宣言しなくても、出力を設定してワークフロー中で利用することはできます。 アクション中での出力の設定に関する詳しい情報については「GitHub Actionsのワークフローコマンド」を参照してください。

サンプル

outputs:
  sum: # 出力のid
    description: '入力の合計'

outputs.<output_id>

必須 文字列型の識別子で、出力と結びつけられます。 <output_id>の値は、出力のメタデータのマップです。 <output_id>は、outputsオブジェクト内でユニークな識別子でなければなりません。 <output_id>は、文字あるいは_で始める必要があり、英数字、-、_しか使用できません。

outputs.<output_id>.description

必須 出力パラメーターの文字列での説明。

複合実行ステップアクションのためのoutputs

オプション outputs outputs.<output_id> および outputs.<output_id>.description（「GitHub Actions の outputs」を参照）と同じパラメーターを使用しますが、value トークンも含まれます。

サンプル

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 をステップの出力値に設定できます。

コンテキストと式の構文の使用方法について詳しくは、「GitHub Actions のコンテキストと式の構文」を参照してください。

JavaScriptアクションのためのruns

必須 アクションのコードと、コードを実行するのに使われるアプリケーションへのパスを設定します。

Node.jsを使用する例

runs:
  using: 'node12'
  main: 'main.js'

runs.using

必須 mainで指定されたコードを実行するのに使われるアプリケーション。

runs.main

必須 アクションのコードを含むファイル。 usingで指定されたアプリケーションがこのファイルを実行します。

pre

オプション main:アクションが開始される前の、ジョブの開始時点でスクリプトを実行できるようにします。 たとえば、pre:を使って必要なセットアップスクリプトを実行できます。 using構文を使って指定されたアプリケーションがこのファイルを実行します。 pre:アクションはデフォルトで常に実行されますが、pre-ifを使ってこれをオーバーライドすることができます。

この例では、pre:アクションはsetup.jsというスクリプトを実行します。

runs:
  using: 'node12'
  pre: 'setup.js'
  main: 'index.js'
  post: 'cleanup.js'

pre-if

オプション pre:アクションの実行条件を定義できるようにしてくれます。 pre:アクションは、pre-if内の条件が満たされたときにのみ実行されます。 設定されなかった場合、pre-ifのデフォルトはalways()になります。 まだステップは実行されていないので、stepコンテキストは利用できないことに注意してください。

以下の例では、cleanup.jsはLinuxベースのランナー上でのみ実行されます。

  pre: 'cleanup.js'
  pre-if: runner.os == 'linux'

post

オプション main:アクションの終了後、ジョブの終わりにスクリプトを実行できるようにします。 たとえば、post:を使って特定のプロセスを終了させたり、不要なファイルを削除したりできます。 using構文を使って指定されたアプリケーションがこのファイルを実行します。

この例では、post:アクションはcleanup.jsというスクリプトを実行します。

runs:
  using: 'node12'
  main: 'index.js'
  post: 'cleanup.js'

post:アクションはデフォルトで常に実行されますが、post-ifを使ってこれをオーバーライドすることができます。

post-if

オプション post:アクションの実行条件を定義できるようにしてくれます。 post:アクションは、post-if内の条件が満たされたときにのみ実行されます。 設定されなかった場合、post-ifのデフォルトはalways()になります。

たとえば、このcleanup.jsはLinuxベースのランナー上でのみ実行されます。

  post: 'cleanup.js'
  post-if: runner.os == 'linux'

複合実行ステップアクションのためのruns

必須 複合アクションへのパス、およびコードの実行に使用されるアプリケーションを設定します。

runs.using

必須 複合実行ステップアクションを使用するには、これを「composite」に設定します。

runs.steps

必須 このアクションで実行する予定の実行ステップ。

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

必須 コマンドを実行するシェル。 こちらにリストされている任意のシェルを使用できます。

runs.steps[*].name

オプション 複合実行ステップの名前。

runs.steps[*].id

オプション ステップの一意の識別子。 idを使って、コンテキストのステップを参照することができます。 詳しい情報については、「GitHub Actions のコンテキストと式構文」を参照してください。

runs.steps[*].env

オプション そのステップのみの環境変数の map を設定します。 ワークフローに保存されている環境変数を変更する場合は、複合実行ステップで }echo "{name}={value}" >> $GITHUB_ENV を使用します。

runs.steps[*].working-directory

オプション コマンドを実行する作業ディレクトリを指定します。

Dockerアクションのためのruns

必須 Dockerアクションのために使われるイメージを設定します。

リポジトリでのDockerfileの利用例

runs:
  using: 'docker'
  image: 'Dockerfile'

パブリックなDockerレジストリコンテナを利用する例

runs:
  using: 'docker'
  image: 'docker://debian:stretch-slim'

runs.using

必須 この値は'docker'に設定しなければなりません。

pre-entrypoint

オプション entrypointアクションが始まる前にスクリプトを実行できるようにしてくれます。 たとえば、pre-entrypoint:を使って必要なセットアップスクリプトを実行できます。 GitHub Actionsはdocker runを使ってこのアクションを起動し、同じベースイメージを使う新しいコンテナ内でスクリプトを実行します。 これはすなわち、ランタイムの状態はメインのentrypointコンテナとは異なるということで、必要な状態はワークスペースやHOME内、あるいはSTATE_変数としてアクセスしなければなりません。 pre-entrypoint:アクションはデフォルトで常に実行されますが、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をオーバーライドします。あるいは、もしそれが指定されていなかった場合に設定します。 entrypointは、DockerfileでENTRYPOINTが指定されていない場合や、ENTRYPOINT命令をオーバーライドしたい場合に使ってください。 entrypointを省略すると、DockerのENTRYPOINT命令で指定されたコマンドが実行されます。 DockerのENTRYPOINT命令には、shell形式とexec形式があります。 DockerのENTRYPOINTのドキュメンテーションは、ENTRYPOINTのexec形式を使うことを勧めています。

entrypointの実行に関する詳しい情報については、「GitHub ActionsのDockerfileサポート」を参照してください。

post-entrypoint

オプション run.entrypointアクションが完了した後に、クリーンアップスクリプトを実行できるようにしてくれます。 GitHub Actionsはこのアクションを起動するのにdocker runを使います。 GitHub Actionsはスクリプトを同じベースイメージを使って新しいコンテナ内で実行するので、ランタイムの状態はメインのentrypointコンテナとは異なります。 必要な状態には、ワークスペースやHOME内、あるいはSTATE_変数としてアクセスできます。 post-entrypoint:アクションはデフォルトで常に実行されますが、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を使うなら、以下の優先順位順のガイドラインを利用してください。

1. 必須の引数をアクションのREADME中でドキュメント化し、CMD命令から除外してください。
2. argsを指定せずにアクションを利用できるよう、デフォルトを使ってください。
3. アクションが--helpフラグやそれに類するものを備えているなら、アクションを自己ドキュメント化するために利用してください。

環境変数をアクションに渡す必要がある場合は、変数置換を行えるようアクションがコマンドシェルで実行されていることを確認してください。 たとえば、entrypoint属性が"sh -c"に設定されているなら、argsはコマンドシェル内で実行されます。 あるいは、DockerfileがENTRYPOINTを使って同じコマンド（"sh -c"）を実行しているなら、argsはコマンドシェル内で実行されます。

GitHub ActionsでのCMD命令の利用に関する詳しい情報については、「GitHub ActionsのDockerfileサポート」を参照してください。

サンプル

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

利用するFeatherアイコンの名前。

activity	airplay	alert-circle	alert-octagon
alert-triangle	align-center	align-justify	align-left
align-right	anchor	aperture	archive
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	bell
bluetooth	bold	book-open	book
bookmark	box	briefcase	calendar
camera-off	camera	cast	check-circle
check-square	check	chevron-down	chevron-left
chevron-right	chevron-up	chevrons-down	chevrons-left
chevrons-right	chevrons-up	circle	clipboard
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
edit	external-link	eye-off	eye
facebook	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	heart
help-circle	home	image	inbox
info	italic	layers	layout
life-buoy	link-2	link	list
loader	lock	log-in	log-out
mail	map-pin	map	maximize-2
maximize	menu	message-circle	message-square
mic-off	mic	minimize-2	minimize
minus-circle	minus-square	minus	monitor
moon	more-horizontal	more-vertical	move
music	navigation-2	navigation	octagon
package	paperclip	pause-circle	pause
percent	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	save	scissors	search
send	server	settings	share-2
share	shield-off	shield	shopping-bag
shopping-cart	shuffle	sidebar	skip-back
skip-forward	slash	sliders	smartphone
speaker	square	Star	stop-circle
sun	sunrise	sunset	tablet
tag	target	terminal	thermometer
thumbs-down	thumbs-up	toggle-left	toggle-right
trash-2	trash	trending-down	trending-up
triangle	truck	tv	type
umbrella	underline	unlock	upload-cloud
upload	user-check	user-minus	user-plus
user-x	user	users	video-off
video	voicemail	volume-1	volume-2
volume-x	volume	Watch	wifi-off
wifi	wind	x-circle	x-square
x	zap-off	zap	zoom-in
zoom-out