GitHub Actionsのメタデータ構文

ここには以下の内容があります:

• GitHub ActionsのYAML構文について
• name
• author
• 説明
• inputs
• outputs
• runs
• branding

GitHub ActionsのYAML構文について

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

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

name

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

author

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

説明

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

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

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

outputs

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

大文字が使われているoutputsのidは、実行時に小文字に変換されます。 outputsのidには小文字を使うことをおすすめします。

outputs.<output_id>

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

outputs.<output_id>.description

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

runs

必須 アクションが実行されたときに走るコマンド。

using

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

Node.jsを使用する例

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

リポジトリ内のDockerfileを利用する例

using: 'docker'
image: 'Dockerfile'

using: 'docker'
image: 'docker://debian:stetch-slim'

env

オプション 仮想環境に設定する環境変数のキー/値のマップを指定します。

main

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

image

コンテナアクションでは必須 コンテナがアクションを実行する際に使用するDockerイメージ。 この値には、Dockerのベースイメージ名、自分のリポジトリ、パブリックなDocker Hubあるいはリポジトリ内のローカルのDockerfileを指定できます。 自分のリポジトリにローカルなDockerfileを参照するには、リポジトリにルートに対する相対的なパスを使ってください。 using構文を使って指定されたアプリケーションがこのファイルを実行します。

自分のリポジトリ内のDockerfileを利用する例

image: 'Dockerfile'

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

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

GitHub上のパブリックなDockerコンテナを利用する例

image: 'actions/container-template@master'

entrypoint

コンテナアクションのオプション Dockerfile中のDockerのENTRYPOINTをオーバーライドします。あるいは、もしそれが指定されていなかった場合に設定します。 アクションがrunsキーワードを使わない場合、このentrypoint内のコマンドが実行されます。 DockerのENTRYPOINT命令にはshell形式とexec形式があります。 DockerのENTRYPOINTのドキュメンテーションでは、ENTRYPOINTの命令としてexec形式を使うことをすすめています。

args

コンテナアクションのオプション Dockerコンテナへの入力を定義する文字列の配列。 入力には、ハードコードされた文字列を含めることができます。 GitHubは、コンテナの起動時にコンテナのENTRYPOINTにargsを渡します。

argsは、Dockerfile中のCMD命令の場所で使われます。 Dockerfile中でCMDを使うなら、以下の優先順位順のガイドラインを利用してください。

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

例

# array format
args: ['${{ inputs.greeting }}', 'foo', 'bar']

# and because it's just YAML, this works:
args:
  - ${{ inputs.greeting }}
  - 'foo'
  - 'bar'

branding

GitHub Marketplaceでアクションをパーソナライズして見分けられるようにするために、カラーとFeatherアイコンを使ってバッジを作ることができます。 詳しい情報についてはGitHub 開発者ドキュメンテーション中の「GitHub Marketplace内でのGitHub Actions」を参照してください。

サンプル

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

color

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

icon

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