Skip to main content

GitHub Actions のメタデータ構文

リポジトリでタスクを実行するアクションを作成できます。 アクションには、YAML 構文を使うメタデータ ファイルが必要です。

GitHub ActionsのYAML構文について

すべてのアクションにメタデータ ファイルが必要です。 メタデータ ファイル名は、action.yml または action.yaml である必要があります。 推奨される形式は action.yml です。 メタデータ ファイル内のデータにより、アクションの入力、出力、実行の構成を定義されます。

アクションのメタデータファイルはYAML構文を使います。 YAML を初めて使用する場合は、「Learn YAML in five minutes」(5 分で学ぶ YAML) を参照してください。

name

必須 アクションの名前。 GitHub の [アクション] タブには name が表示され、各ジョブのアクションを視覚的に特定するのに役立ちます。

author

省略可能 アクションの作成者の名前。

description

必須 アクションの簡単な説明。

inputs

省略可能 入力パラメーターでは、実行時にアクションで使用するデータを指定できます。 GitHubは、inputsパラメータを環境変数として保存します。 inputsの id には小文字を使うことをおすすめします。

例: 入力の指定

この例では、num-octocatsoctocat-eye-color という 2 つの入力を構成しています。 num-octocats 入力は必須ではなく、既定の値は 1 になります。 octocat-eye-color は必須で、既定値はありません。

Note

入力が指定されていない場合、required: true を使用するアクションは自動的にエラーを返しません。

このアクションが使用されているワークフロー ファイルでは、with キーワードを使って、octocat-eye-color の入力値を設定できます。 with 構文の詳細については、「GitHub Actions のワークフロー構文」を参照してください。

inputs:
  num-octocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocat-eye-color:
    description: 'Eye color of the Octocats'
    required: true

入力を指定すると、GitHub により、その入力に対して、INPUT_<VARIABLE_NAME> という名前の環境変数が作成されます。 作成された環境変数では、入力名を大文字に変換し、空白を _ 文字に置き換えます。

アクションが composite を使用して書き込まれている場合は、自動的に INPUT_<VARIABLE_NAME> が取得されません。 複合アクションを使用すると、inputs ワークフロー実行に関するコンテキスト情報へのアクセス を使用してアクション入力にアクセスできます。

Docker コンテナー アクションの環境変数にアクセスするには、アクション メタデータ ファイルで args キーワードを使用して入力を渡す必要があります。 Docker コンテナー アクションのアクション メタデータ ファイルの詳細については、「Docker コンテナーのアクションを作成する」を参照してください。

たとえば、ワークフローで num-octocats および octocat-eye-color 入力が定義されている場合は、アクション コードで、INPUT_NUM-OCTOCATS および INPUT_OCTOCAT-EYE-COLOR 環境変数を使用して入力の値を読み取ることができます。

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 "random-id=$(echo $RANDOM)" >> $GITHUB_OUTPUT
      shell: bash

outputs.<output_id>.value

必須 出力パラメーターがマップされる値。 これは、string またはコンテキスト付きの式に設定できます。 たとえば、steps コンテキストを使用して、出力の value をステップの出力値に設定できます。

コンテキスト構文の使い方の詳細については、「ワークフロー実行に関するコンテキスト情報へのアクセス」を参照してください。

runs

必須 これが JavaScript アクション、複合アクション、Docker コンテナー アクションのいずれであるか、およびアクションの実行方法を指定します。

JavaScript のアクションの runs

必須 アクションのコードへのパスと、コードの実行に使用されるランタイムを構成します。

例: Node.js v20 を使用する

runs:
  using: 'node20'
  main: 'main.js'

JavaScript のアクションの runs.using

必須 main で指定されたコードを実行するために使用されるランタイム。

  • Node.js v20 では node20 を使用する。

runs.main

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

runs.pre

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

この例では、pre: アクションによって setup.js というスクリプトが実行されます。

runs:
  using: 'node20'
  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: 'node20'
  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

詳しくは、「ワークフロー実行に関するコンテキスト情報へのアクセス」をご覧ください。

runs.steps[*].shell

省略可能 コマンドを実行するシェル。 「GitHub Actions のワークフロー構文」に記載されているシェルのいずれかを使用できます。 run が設定されている場合は必須です。

runs.steps[*].if

省略可能 if 条件文を使って、条件が満たされなければ、ステップを実行しないようにすることができます。 条件文を作成するには、サポートされている任意のコンテキストや式が使えます。

if 条件の中で式を使う際には、任意で式構文 ${{ }} を省略できます。これは、GitHub Actions が if 条件を式として自動的に評価するためです。 ただし、この例外はどこでも適用されるわけではありません。

! は YAML 形式で予約された表記であるため、必ず${{ }} 構文の式を使用するか、式が ! で始まる場合は ''""、または () でエスケープする必要があります。 次に例を示します。

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

詳細については、「ワークフローとアクションで式を評価する」を参照してください。

例: コンテキストの使用

このステップは、イベントの種類が pull_request で、イベント アクションが unassigned である場合にのみ実行されます。

steps:
  - run: echo This event is a pull request that had an assignee removed.
    if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}

例: ステータス チェック関数の使用

複合アクションの前のステップが失敗した場合にのみ、my backup step が実行されます。 詳しくは、「ワークフローとアクションで式を評価する」をご覧ください。

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

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@8f4b7f84864484a7bf31766abe9204da3cbe65b3
    # Reference the major version of a release
    - uses: actions/checkout@v4
    # Reference a specific version
    - uses: actions/checkout@v4.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'

Docker コンテナー アクションの 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 をオーバーライドするか、まだ指定されていない場合は設定します。 DockerfileENTRYPOINT が指定されていない場合や、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 命令の代わりに使用されます。 ご自分の DockerfileCMD を使用する場合は、以下の優先順のガイドラインを使用してください。

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

環境変数をアクションに渡す必要がある場合は、変数置換を行えるようアクションがコマンドシェルで実行されていることを確認してください。 たとえば、entrypoint 属性が "sh -c" に設定されている場合は、args がコマンド シェルで実行されます。 あるいは、DockerfileENTRYPOINT を使用して同じコマンド ("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

バッジの背景カラー。 whiteblackyellowbluegreenorangeredpurplegray-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
  • 日没
  • テーブル
  • タブレット
  • タグ
  • ターゲット (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

メタデータ ファイル名を変更する

アクションのメタデータ ファイルは両方の YAML 形式をサポートしていますが、リリース間でメタデータ ファイル名を変更 (action.yml から action.yaml またはその逆) すると、GitHub Marketplace に公開されている以前のリリース バージョンに影響します。 ファイル名を変更すると、以前のファイル名に関連付けられているすべてのリリース バージョンが GitHub Marketplace に表示されなくなります。 以前のリリース バージョンには、ソース リポジトリを介してユーザーは引き続きアクセスできます。

新しいバージョンのアクションをリリースすると、メタデータ ファイル名の変更後にリリースされたバージョンのみが GitHub Marketplace タグを持ち、GitHub Marketplace に表示されます