Skip to main content

GitHub Actions のメタデータ構文

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

注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。

GitHub ActionsのYAML構文について

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

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

name

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

author

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

description

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

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> という名前の環境変数が作成されます。 作成された環境変数では、入力名を大文字に変換し、空白を _ 文字に置き換えます。

アクションが composite を使用して書き込まれている場合は、自動的に INPUT_<VARIABLE_NAME> が取得されません。 変換されない場合は、これらの入力を手動で変更できます。

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

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

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

outputs.<output_id>.value

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

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

runs

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

JavaScript のアクションの runs

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

例: Node.js v16 の使用

runs:
  using: 'node16'
  main: 'main.js'

runs.using

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

  • Node.js v12 では node12 を使用。
  • Node.js v16 では node16 を使用。

runs.main

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

runs.pre

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

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

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

詳細については、github context を参照してください。

runs.steps[*].shell

省略可能 コマンドを実行するシェル。 ここに一覧表示されているシェルのいずれかを使用できます。 run が設定されている場合は必須です。

runs.steps[*].if

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

if 条件の中で式を使う際には、式構文 (${{ }})を省略できます。これは、GitHub が if 条件を式として自動的に評価するためです。 詳細については、「」を参照してください。

例: コンテキストの使用

このステップは、イベントの種類が 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@a81bbbf8298c0fa03ea29cdc473d45769f953675
    # Reference the major version of a release
    - uses: actions/checkout@v3
    # Reference a specific version
    - uses: actions/checkout@v3.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'

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

バッジの背景カラー。 whiteyellowbluegreenorangeredpurplegray-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 sunset タブレット タグ
ターゲット (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