GitHub Actionsのメタデータ構文

GitHub ActionsのYAML構文について

All actions require a metadata file. このメタデータのファイル名はaction.ymlもしくはaction.yamlでなければなりません。 The data in the metadata file defines the inputs, outputs, and runs configuration for your action.

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

name

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

作者

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

説明

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

inputs

オプション inputsパラメーターを使うと、アクションが実行時に使うデータを指定できます。 GitHubは、inputsパラメータを環境変数として保存します。 大文字が使われているInputsのidは、実行時に小文字に変換されます。 inputsのidには小文字を使うことをおすすめします。

Example: Specifying inputs

この例では、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

When you specify an input in a workflow file or use a default input value, GitHub creates an environment variable for the input with the name INPUT_<VARIABLE_NAME>. 生成される環境変数では、入力の名前を大文字にして、空白を_に変換します。

If the action is written using a composite, then it will not automatically get INPUT_<VARIABLE_NAME>. If the conversion doesn't occur, you can change these inputs manually.

To access the environment variable in a Docker container action, you must pass the input using the args keyword in the action metadata file. For more information about the action metadata file for Docker container actions, see "Creating a Docker container action."

たとえば、ワークフローで 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 for Docker container and JavaScript actions

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

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

Example: Declaring outputs for Docker container and JavaScript actions

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

outputs.<output_id>

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

outputs.<output_id>.description

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

outputs for composite actions

Optional outputs use the same parameters as outputs.<output_id> and outputs.<output_id>.description (see "outputs for Docker container and JavaScript actions"), but also includes the value token.

Example: Declaring outputs for composite actions

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

For more information on how to use context syntax, see "Contexts."

runs

Required Specifies whether this is a JavaScript action, a composite action, or a Docker container action and how the action is executed.

JavaScriptアクションのためのruns

Required Configures the path to the action's code and the runtime used to execute the code.

Example: Using Node.js v12

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

runs.using

Required The runtime used to execute the code specified in main.

• Use node12 for Node.js v12.

runs.main

必� � アクションのコードを含むファイル。 The runtime specified in using executes this file.

runs.pre

オプション main:アクションが開始される前の、ジョブの開始時点でスクリプトを実行できるようにします。 たとえば、pre:を使って必要なセットアップスクリプトを実行できます。 The runtime specified with the using syntax will execute this file. The pre: action always runs by default but you can override this using 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()になります。 In pre-if, status check functions evaluate against the job's status, not the action's own status.

ま� ステップは実行されていないので、stepコンテキストは利用できないことに注意してく� さい。

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

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

runs.post

オプション main:アクションの終了後、ジョブの終わりにスクリプトを実行できるようにします。 たとえば、post:を使って特定のプロセスを終了させたり、不要なファイルを削除したりできます。 The runtime specified with the using syntax will execute this file.

この例では、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()になります。 In post-if, status check functions evaluate against the job's status, not the action's own status.

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

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

runs for composite actions

Required Configures the path to the composite action.

runs.using

Required You must set this value to 'composite'.

runs.steps

Required The steps that you plan to run in this action.

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

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

runs.steps[*].name

Optional The name of the composite step.

runs.steps[*].id

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

runs.steps[*].env

オプション そのステップのみの環境変数の map を設定します。 If you want to modify the environment variable stored in the workflow, use echo "{name}={value}" >> $GITHUB_ENV in a composite step.

runs.steps[*].working-directory

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

runs for Docker container actions

Required Configures the image used for the Docker container action.

Example: Using a Dockerfile in your repository

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

Example: Using public Docker registry container

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

runs.using

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

runs.pre-entrypoint

オプション entrypointアクションが始まる前にスクリプトを実行できるようにしてくれます。 たとえば、pre-entrypoint:を使って必要なセットアップスクリプトを実行できます。 GitHub Actionsはdocker runを使ってこのアクションを起動し、同じベースイメージを使う新しいコンテナ内でスクリプトを実行します。 これはすなわち、ランタイ� の状態はメインのentrypointコンテナとは異なるということで、必要な状態はワークスペースやHOME内、あるいはSTATE_変数としてアクセスしなければなりません。 The pre-entrypoint: action always runs by default but you can override this using runs.pre-if.

The runtime specified with the using syntax will execute this file.

この例では、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_変数としてアクセスできます。 The post-entrypoint: action always runs by default but you can override this using 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を使うなら、以下の優先� �位� �のガイドラインを利用してく� さい。

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

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

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

Example: Defining arguments for the Docker container

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.greeting }}
    - 'foo'
    - 'bar'

branding

アクションをパーソナライズして見分けられるようにするために、カラーとFeatherアイコンを使ってバッジを作ることができます。 バッジは、GitHub Marketplace内のアクション名の隣に表示されます。

Example: Configuring branding for an action

branding:
  icon: 'award'  
  color: 'green'

branding.color

バッジの背景カラー。 white、yellow、blue、green、orange、red、purple、gray-darkのいずれか。

branding.icon

The name of the v4.28.0 Feather icon to use. Brand icons are omitted as well as the following:

coffee	カラ�	divide-circle	divide-square
divide	frown	hexagon	key
meh	mouse-pointer	smile	ツール
x-octagon

Here is an exhaustive list of all currently supported icons:

アクティビティ	airplay	alert-circle	alert-octagon
alert-triangle	align-center	align-justify	align-left
align-right	anchor	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	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	コード
コマンド	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	ファイル	film
filter	フラグ	folder-minus	folder-plus
folder	gift	git-branch	git-commit
git-merge	git-pull-request	globe	grid
hard-drive	ハッシュ	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	巻き戻し	rotate-ccw	rotate-cw
rss	保存	scissors	search
send	server	settings	share-2
share	shield-off	shield	shopping-bag
shopping-cart	shuffle	サイドバー	skip-back
skip-forward	slash	sliders	smartphone
speaker	square	Star	stop-circle
sun	sunrise	sunset	tablet
タグ	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
アップロード	user-check	user-minus	user-plus
user-x	ユーザ	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