ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

GitHub Actionsのメタデータ構文

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

GitHub ActionsはGitHub Free、GitHub Pro、GitHub FreeのOrganization、GitHub Team、GitHub Enterprise Cloud、GitHub Oneで利用できます。 GitHub Actionsは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。 For more information, see "GitHub's products."

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

Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

OR, learn how to contribute.

GitHub Actions の支払いを管理する GitHubは、macOSランナーのホストにMacStadiumを使用しています。

GitHub ActionsのYAML構文について

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

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

name

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

作者

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

説明

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

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

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

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

サンプル

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

outputs.<output_id>

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

outputs.<output_id>.description

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

複合実行ステップアクションのための outputs

オプション outputs outputs.<output_id> および outputs.<output_id>.description(「GitHub Actions の outputs」を参照)と同じパラメーターを使用しますが、value トークンも含まれます。

サンプル

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

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

JavaScriptアクションのためのruns

必須 アクションのコードと、コードを実行するのに使われるアプリケーションへのパスを設定します。

Node.jsを使用する例

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

runs.using

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

runs.main

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

pre

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

この例では、pre:アクションはsetup.jsというスクリプトを実行します。

runs:
  using: 'node12'
  pre: 'setup.js'
  main: 'index.js'
  post: 'cleanup.js'

pre-if

オプション pre:アクションの実行条件を定義できるようにしてくれます。 pre:アクションは、pre-if内の条件が満たされたときにのみ実行されます。 設定されなかった場合、pre-ifのデフォルトはalways()になります。 まだステップは実行されていないので、stepコンテキストは利用できないことに注意してください。

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

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

post

オプション main:アクションの終了後、ジョブの終わりにスクリプトを実行できるようにします。 たとえば、post:を使って特定のプロセスを終了させたり、不要なファイルを削除したりできます。 using構文を使って指定されたアプリケーションがこのファイルを実行します。

この例では、post:アクションはcleanup.jsというスクリプトを実行します。

runs:
  using: 'node12'
  main: 'index.js'
  post: 'cleanup.js'

post:アクションはデフォルトで常に実行されますが、post-ifを使ってこれをオーバーライドすることができます。

post-if

オプション post:アクションの実行条件を定義できるようにしてくれます。 post:アクションは、post-if内の条件が満たされたときにのみ実行されます。 設定されなかった場合、post-ifのデフォルトはalways()になります。

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

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

複合実行ステップアクションのための runs

必須 複合アクションへのパス、およびコードの実行に使用されるアプリケーションを設定します。

runs.using

必須 複合実行ステップアクションを使用するには、これを「composite」に設定します。

runs.steps

必須 このアクションで実行する予定の実行ステップ。

runs.steps.run

必須 実行するコマンド。 これは、インラインでも、アクションリポジトリ内のスクリプトでもかまいません。

runs:
  using: "composite"
  steps: 
    - run: $/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

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

runs.steps.name

オプション 複合実行ステップの名前。

runs.steps.id

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

runs.steps.env

オプション そのステップのみの環境変数の map を設定します。 ワークフローに保存されている環境変数を変更する場合は、複合実行ステップで echo "{name}={value}" >> $GITHUB_ENV を使用します。

runs.steps.working-directory

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

Dockerアクションのためのruns

必須 Dockerアクションのために使われるイメージを設定します。

リポジトリでのDockerfileの利用例

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

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

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

runs.using

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

pre-entrypoint

オプション entrypointアクションが始まる前にスクリプトを実行できるようにしてくれます。 たとえば、pre-entrypoint:を使って必要なセットアップスクリプトを実行できます。 GitHub Actionsはdocker runを使ってこのアクションを起動し、同じベースイメージを使う新しいコンテナ内でスクリプトを実行します。 これはすなわち、ランタイムの状態はメインのentrypointコンテナとは異なるということで、必要な状態はワークスペースやHOME内、あるいはSTATE_変数としてアクセスしなければなりません。 pre-entrypoint:アクションはデフォルトで常に実行されますが、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を参照するには、アクションのメタデータファイルに対する相対的なパスを使ってください。 dockerアプリケーションがこのファイルを実行します。

runs.env

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

runs.entrypoint

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

entrypointの実行に関する詳しい情報については、「GitHub ActionsのDockerfileサポート」を参照してください。

post-entrypoint

オプション run.entrypointアクションが完了した後に、クリーンアップスクリプトを実行できるようにしてくれます。 GitHub Actionsはこのアクションを起動するのにdocker runを使います。 GitHub Actionsはスクリプトを同じベースイメージを使って新しいコンテナ内で実行するので、ランタイムの状態はメインのentrypointコンテナとは異なります。 必要な状態には、ワークスペースやHOME内、あるいはSTATE_変数としてアクセスできます。 post-entrypoint:アクションはデフォルトで常に実行されますが、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はコマンドシェル内で実行されます。 あるいは、DockerfileENTRYPOINTを使って同じコマンド("sh -c")を実行しているなら、argsはコマンドシェル内で実行されます。

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

サンプル
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

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

アクティビティ 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 save 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

Did this doc help you?

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

OR, learn how to contribute.