GitHub Actionsの各種構文のinputsの振る舞いの違いについて

2025-02-13

• #devops

はじめに

こんにちは。SRE チーム所属の Kentaro です。

直近で CircleCI から GitHub Actions 移行を進めていました。

今回は移行を進めていく中で学んだ GitHub Actions で利用できる各種構文の inputs 属性の違いについて紹介します。

利用できる構文の種類

GitHub Actions では以下の構文を利用することができます。

• Workflow 構文
  • 主に.github/workflows 配下に配置されるもの
  • https://docs.github.com/ja/actions/writing-workflows/workflow-syntax-for-github-actions
• メタデータ構文
  • 一般的には.github/actions 配下に配置されることが多いもの
  • https://docs.github.com/ja/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions

Workflow 構文について

Workflow 構文については、さらに以下の用途が存在しています。

• イベントを使って Workflow を実行するもの
  • pull request や push のタイミングで実行するもの
• 手動で実行する Workflow
  • GitHub 上からユーザー自身の手で、手動で実行するもの
• Required Workflow
  • 組織内のすべてのリポジトリ、または選択したリポジトリに対して共通でチェックしたいものを実行するもの
• 他のワークフローから再利用する形で実行するもの
  • Reusable Workflow という名前で呼ばれています

各種構文で利用できる inputs 属性について

紹介してきた中で以下 3 つの構文については、入力値として inputs 属性の定義を行うことができます。

• メタデータ構文
• 手動で実行する Workflow
• Reusable Workflow

処理のイメージとしては、以下のようなイメージです。

inputs:
  name:
    description: order name
    required: true

入力値としての inputs 属性は上記 3 つの構文で利用できますが、実は各種構文ごとに微妙に振る舞いがことなってきます。

この振る舞いの違いについて、以降記載していきます。

required 属性について

inputs 属性には required 属性を付与することができます。

例えば以下のような形です。

inputs:
  service_name:
    description: put a cloud run service name to deploy
    required: true

基本的な振る舞いとしては、required 属性で指定された input が来なかった場合、指定されたものがないといったエラーが出ます。

ただメタデータ構文については、required 属性を付与したとしても付与された required 属性は、単純なドキュメント的な意味しかもちません。

Actions using required: true will not automatically return an error if the input is not specified.

https://docs.github.com/ja/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#inputs

そのためメタデータ構文の inputs 属性の中で必須じゃないと困るものは、自前でエラー処理を入れる必要があります。

例えば明示的にエラーにして該当のアクションを止めたい場合は、以下のように処理を追加する必要があります。

runs:
  using: composite
  steps:
    - name: Throw Invalid Variable Type Error
      if: ${{ inputs.service_name == ''}}
      shell: bash
      run: |
        echo "::error::Invalid type of argument."
        exit 1

指定できる type 属性について

GitHub Actions では入力値となる inputs 属性に type 属性を指定することで、渡ってくる入力値に対して型を割り当てることができます。

各種構文において指定できる type 属性に違いがあります。

メタデータ構文の場合

メタデータ構文では実は type 属性を指定することができません。

そのためメタデータ構文ではどの値を指定しても string 型として解釈が行われます。

参考：https://docs.github.com/ja/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#inputs

手動で実行する Workflow の場合

手動で実行する Workflow の場合はそれぞれ以下の type 属性を指定することができます。

• string
• boolean
• number
• choice
  • 事前に定義した値のみが指定できる
• environment
  • リポジトリに設定した environment の種類を表示できる

参考：https://docs.github.com/ja/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_dispatchinputsinput_idtype

Reusable Workflow の場合

Reusable Workflow の場合はそれぞれ以下の type 属性を指定することができます。

• string
• boolean
• number

参考：https://docs.github.com/ja/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_callinputsinput_idtype

default 値について

default 値は inputs 属性上で default 属性を用いて指定したり、required false などを記載すると Github Actions 側で適当な値が割り当てられます。

この GitHub Actions 側で割り当てられる値についても各種構文で微妙に違いがあります。

メタデータ構文の場合

メタデータ構文では、type 属性自体を指定することができません。

そのため default 属性が指定されていない場合は、空文字が渡ってきます。

参考：https://docs.github.com/ja/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions

手動で実行する Workflow の場合

手動で実行する Workflow の場合は、GitHub Actions 側で各 type 属性に合わせて以下の値が割り当てられます。

• type: string の場合
  • 空文字
• type: number の場合
  • 数字の 0
• type: bool の場合
  • bool の false

Reusable Workflow の場合

Reusable Workflow の場合の場合は、GitHub Actions 側で各 type 属性に合わせて以下の値が割り当てられます。

• type: string の場合
  • 空文字
• type: number の場合
  • 数字の 0
• type: bool の場合
  • bool の false

参考：https://docs.github.com/ja/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_callinputs

GitHub Actions Inputs 属性の違いまとめ

最後に各構文のまとめを表にしておきます。

特性	メタデータ構文	手動で実行する Workflow	Reusable Workflow
構文配置場所	.github/actions 配下 (一般的)	.github/workflows 配下	.github/workflows 配下
required属性	ドキュメント的な意味しか持たないため、自前でエラー処理が必要。	trueに指定された input がない場合エラーが発生。	trueに指定された input がない場合エラーが発生。
type属性	指定不可。すべて string 型として解釈。	string, boolean, number, choice, environment	string, boolean, number
default値指定なしの場合	空文字 ("") が渡される。	type属性が指定されていない場合、type属性は必須なためエラーになる。	type属性が指定されていない場合、type属性は必須なためエラーになる。
default値指定なし + 各type属性の場合	空文字 ("") が渡される。	string: 空文字 ("") number: 0 boolean: false	string: 空文字 ("") number: 0 boolean: false

また、弊社 Belong では一緒に働く仲間を募集しています。

興味がある方は エンジニアリングチーム紹介ページ をご覧いただけると幸いです。