ノート: GitHub Actionsは、GitHub Enterprise Server 2.22で限定ベータとして利用可能でした。 ベータは終了しました。 GitHub Actionsは、GitHub Enterprise Server 3.0以降で一般に利用可能になりました。 詳しい情報については、GitHub Enterprise Server 3.0 のリリースノートを参照してください。
- GitHub Enterprise Server 3.0以降へのアップグレードに関する詳しい情報については「GitHub Enterprise Serverのアップグレード」を参照してください。
- アップグレード後のGitHub Actionsの設定に関する詳しい情報については、GitHub Enterprise Server 3.0のドキュメンテーションを参照してください。
ノート: GitHubホストランナーは、現在GitHub Enterprise Serverでサポートされていません。 GitHubパブリックロードマップで、計画されている将来のサポートに関する詳しい情報を見ることができます。
GitHub ActionsのYAML構文について
Docker及びJavaScriptアクションにはメタデータファイルが必要です。 このメタデータのファイル名はaction.yml
もしくはaction.yaml
でなければなりません。 メタデータファイル中のデータは、アクションの入力、出力、メインエントリポイントを定義します。
アクションのメタデータファイルはYAML構文を使います。 YAMLについて詳しくない場合は、「Learn YAML in five minutes (5分で学ぶYAML)」をお読みください。
name
Required The name of your action. GitHub displays the name
in the Actions tab to help visually identify actions in each job.
作者
Optional The name of the action's author.
説明
Required A short description of the action.
inputs
Optional Input parameters allow you to specify data that the action expects to use during runtime. 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
When you specify an input in a workflow file or use a default input value, GitHub creates an environment variable for the input with the name INPUT_<VARIABLE_NAME>
. 生成される環境変数では、入力の名前を大文字にして、空白を_
に変換します。
If the action is written using a composite, then it will not automatically get INPUT_<VARIABLE_NAME>
. If the conversion doesn't occur, you can change these inputs manually.
To access the environment variable in a Docker container action, you must pass the input using the args
keyword in the action metadata file. For more information about the action metadata file for Docker container actions, see "Creating a Docker container action."
たとえば、ワークフローで numOctocats
および octocatEyeColor
入力が定義されている場合、アクションコードは INPUT_NUMOCTOCATS
および INPUT_OCTOCATEYECOLOR
環境変数を使用して入力の値を読み取ることができます。
inputs.<input_id>
Required A string
identifier to associate with the input. <input_id>
の値は、入力のメタデータのマップです。 <input_id>
は、inputs
オブジェクト内でユニークな識別子でなければなりません。 <input_id>
は、文字あるいは_
で始める必要があり、英数字、-
、_
しか使用できません。
inputs.<input_id>.description
Required A string
description of the input parameter.
inputs.<input_id>.required
Required A boolean
to indicate whether the action requires the input parameter. パラメーターが必須の場合はtrue
に設定してください。
inputs.<input_id>.default
Optional A string
representing the default value. デフォルト値は、入力パラメーターがワークフローファイルで指定されなかった場合に使われます。
inputs.<input_id>.deprecationMessage
オプション 入力パラメータが使用されている場合、この string
は警告メッセージとしてログに記録されます。 この警告で入力が非推奨であることをユーザに通知し、その他の方法を知らせることができます。
outputs
オプション アクションが設定するデータを宣言できる出力パラメータ。 ワークフローで後に実行されるアクションは、先行して実行されたアクションが設定した出力データを利用できます。 たとえば、2つの入力を加算(x + y = z)するアクションがあれば、そのアクションは他のアクションが入力として利用できる合計値(z)を出力できます。
メタデータファイル中でアクション内の出力を宣言しなくても、出力を設定してワークフロー中で利用することはできます。 アクション中での出力の設定に関する詳しい情報については「GitHub Actionsのワークフローコマンド」を参照してください。
サンプル
outputs:
sum: # 出力のid
description: '入力の合計'
outputs.<output_id>
Required A string
identifier to associate with the output. <output_id>
の値は、出力のメタデータのマップです。 <output_id>
は、outputs
オブジェクト内でユニークな識別子でなければなりません。 <output_id>
は、文字あるいは_
で始める必要があり、英数字、-
、_
しか使用できません。
outputs.<output_id>.description
Required A string
description of the output parameter.
outputs
for composite actions
オプション 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
をステップの出力値に設定できます。
For more information on how to use context syntax, see "Contexts."
JavaScriptアクションのためのruns
必須 アクションのコードと、コードを実行するのに使われるアプリケーションへのパスを設定します。
Node.jsを使用する例
runs:
using: 'node12'
main: 'main.js'
runs.using
必須 main
で指定されたコードを実行するのに使われるアプリケーション。
runs.main
必須 アクションのコードを含むファイル。 using
で指定されたアプリケーションがこのファイルを実行します。
pre
オプション main:
アクションが開始される前の、ジョブの開始時点でスクリプトを実行できるようにします。 たとえば、pre:
を使って必要なセットアップスクリプトを実行できます。 The application specified with the using
syntax will execute this file. 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:
を使って特定のプロセスを終了させたり、不要なファイルを削除したりできます。 The application specified with the using
syntax will execute this file.
この例では、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
for composite actions
必須 複合アクションへのパス、およびコードの実行に使用されるアプリケーションを設定します。
runs.using
Required To use a composite action, set this to "composite"
.
runs.steps
Required The steps that you plan to run in this action.
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
必須 コマンドを実行するシェル。 こちらにリストされている任意のシェルを使用できます。 Required if run
is set.
runs.steps[*].name
Optional The name of the composite step.
runs.steps[*].id
オプション ステップの一意の識別子。 id
を使って、コンテキストのステップを参照することができます。 詳細については、「コンテキスト」を参照してください。
runs.steps[*].env
オプション そのステップのみの環境変数の map
を設定します。 If you want to modify the environment variable stored in the workflow, use echo "::set-env name={name}::{value}"
in a composite step.
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
を使ってこれをオーバーライドすることができます。
The application specified with the using
syntax will execute this file.
この例では、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
をオーバーライドします。あるいは、もしそれが指定されていなかった場合に設定します。 entrypoint
は、Dockerfile
でENTRYPOINT
が指定されていない場合や、ENTRYPOINT
命令をオーバーライドしたい場合に使ってください。 entrypoint
を省略すると、DockerのENTRYPOINT
命令で指定されたコマンドが実行されます。 DockerのENTRYPOINT
命令には、shell形式とexec形式があります。 DockerのENTRYPOINT
のドキュメンテーションは、ENTRYPOINT
のexec形式を使うことを勧めています。
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
を使うなら、以下の優先順位順のガイドラインを利用してください。
- 必須の引数をアクションのREADME中でドキュメント化し、
CMD
命令から除外してください。 args
を指定せずにアクションを利用できるよう、デフォルトを使ってください。- アクションが
--help
フラグやそれに類するものを備えているなら、アクションを自己ドキュメント化するために利用してください。
環境変数をアクションに渡す必要がある場合は、変数置換を行えるようアクションがコマンドシェルで実行されていることを確認してください。 たとえば、entrypoint
属性が"sh -c"
に設定されているなら、args
はコマンドシェル内で実行されます。 あるいは、Dockerfile
がENTRYPOINT
を使って同じコマンド("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
バッジの背景カラー。 white
、yellow
、blue
、green
、orange
、red
、purple
、gray-dark
のいずれか。
branding.icon
利用するFeatherアイコンの名前。
activity | airplay | alert-circle | alert-octagon |
alert-triangle | align-center | align-justify | align-left |
align-right | anchor | aperture | archive |
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 | 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 |
edit | 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 | heart |
help-circle | home | image | inbox |
info | italic | layers | layout |
life-buoy | link-2 | link | list |
loader | lock | log-in | log-out |
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 | power | |
printer | radio | refresh-ccw | refresh-cw |
repeat | rewind | rotate-ccw | rotate-cw |
rss | save | scissors | search |
send | server | settings | share-2 |
share | shield-off | shield | shopping-bag |
shopping-cart | shuffle | sidebar | skip-back |
skip-forward | slash | sliders | smartphone |
speaker | square | Star | stop-circle |
sun | sunrise | sunset | tablet |
tag | 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 |
upload | user-check | user-minus | user-plus |
user-x | user | 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 |