GitHub ActionsのためのDockerfileサポート

Docker コンテナー アクション用の Dockerfile を作成する際には、いくつかの Docker の命令が GitHub Actions やアクションのメタデータ ファイルとどのように関わるのかを知っておく必要があります。

この記事の内容

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

Dockerfileの命令について

Dockerfile には、Docker コンテナーの内容と起動時の動作を定義する命令と引数が含まれています。 Docker がサポートする手順の詳細については、Docker ドキュメントの「Dockerfile リファレンス」を参照してください。

Dockerfileの命令とオーバーライド

Dockerの命令の中にはGitHub Actionsと関わるものがあり、アクションのメタデータファイルはDockerの命令のいくつかをオーバーライドできます。 予期しない動作を避けるために、DockerfileがGitHub Actionsとどのように関わるかについて馴染んでおいてください。

User

DockerアクションはデフォルトのDockerユーザ（root）で実行されなければなりません。 Dockerfile では USER 命令を使用しないでください。そうしないと、GITHUB_WORKSPACE ディレクトリにアクセスできなくなります。 詳しくは、「変数に情報を格納する」と、Docker のドキュメントの USER リファレンスをご覧ください。

FROM

Dockerfile の最初の命令は、FROM とする必要があります。これにより、Docker ベース イメージが選択されます。 詳細については、Docker ドキュメントの FROM リファレンスを参照してください。

FROM 引数の設定には、いくつかのベストプラクティスがあります。

  • 公式のDockerイメージを使うことをおすすめします。 たとえば、python または ruby です。
  • バージョンタグが存在する場合は使ってください。メジャーバージョンも含めることが望ましいです。 たとえば、node:latest の代わりに node:10 を使用します。
  • Debian オペレーティング システムに基づいて Docker イメージを使用することをお勧めします。

WORKDIR

GitHub Enterprise Server では、ワーキング ディレクトリのパスを環境変数 GITHUB_WORKSPACE に設定します。 Dockerfile では、WORKDIR 命令を使用しないことをお勧めします。 アクションが実行される前に、GitHub Enterprise Server では、GITHUB_WORKSPACE ディレクトリを、Docker イメージ内にあったその場所になにがあってもその上にマウントし、GITHUB_WORKSPACE をワーキング ディレクトリとして設定します。 詳しくは、「変数に情報を格納する」と、Docker のドキュメントの WORKDIR リファレンスをご覧ください。

ENTRYPOINT

アクションのメタデータ ファイルで entrypoint を定義すると、それによって、Dockerfile 内に定義されている ENTRYPOINT がオーバーライドされます。 詳しくは、「GitHub Actions のメタデータ構文」を参照してください。

Docker の ENTRYPOINT 命令には、shell 形式と exec 形式があります。 Docker ENTRYPOINT ドキュメントでは、ENTRYPOINT 命令の exec 形式を使用することを推奨しています。 exec 形式と shell 形式の詳細については、Docker ドキュメントの ENTRYPOINT リファレンスを参照してください。

Dockerfile でエントリポイントを指定する場合は、WORKDIR を使用しないでください。 代わりに、絶対パスを使用する必要があります。 詳細については、「WORKDIR」を参照してください。

ENTRYPOINT 命令の exec 形式を使用するようにコンテナーを構成した場合、アクションのメタデータ ファイルで構成された args はコマンド シェルで実行されません。 アクションの args に環境変数が含まれている場合、その変数は置換されません。 たとえば、次の exec 形式を使用すると、$GITHUB_SHA に格納されている値は出力されませんが、代わりに "$GITHUB_SHA" が出力されます。

ENTRYPOINT ["echo $GITHUB_SHA"]

変数の置換が必要な場合は、shell 形式を使用するか、直接シェルを実行してください。 たとえば、以下の exec 形式を使用すれば、シェルを実行して環境変数 GITHUB_SHA に保存された値を出力できます。

ENTRYPOINT ["sh", "-c", "echo $GITHUB_SHA"]

アクションのメタデータ ファイルで定義されている args を、ENTRYPOINT で exec 形式を使用している Docker コンテナーに指定するには、ENTRYPOINT 命令から呼び出す entrypoint.sh というシェル スクリプトを作成することをお勧めします。

Dockerfile の例

# Container image that runs your code
FROM debian:9.5-slim

# Copies your code file from your action repository to the filesystem path `/` of the container
COPY entrypoint.sh /entrypoint.sh

# Executes `entrypoint.sh` when the Docker container starts up
ENTRYPOINT ["/entrypoint.sh"]

entrypoint.sh ファイルの例

上の Dockerfile を使用すると、GitHub Enterprise Server によって、アクションのメタデータ ファイル内に引数として構成された argsが entrypoint.sh に送信されます。 entrypoint.sh ファイルの先頭に #!/bin/sh shebang を追加して、システムの POSIX準拠のシェルを明示的に使用します。

#!/bin/sh

# `$#` expands to the number of arguments and `$@` expands to the supplied `args`
printf '%d args:' "$#"
printf " '%s'" "$@"
printf '\n'

コードは実行可能になっていなければなりません。 ワークフローで使用する前に、entrypoint.sh ファイルに execute アクセス許可があることを確認します。 この権限は、ターミナルから以下のコマンドで変更できます。

chmod +x entrypoint.sh

ENTRYPOINT シェル スクリプトが実行可能ではなかった場合、以下のようなエラーが返されます。

Error response from daemon: OCI runtime create failed: container_linux.go:348: starting container process caused "exec: \"/entrypoint.sh\": permission denied": unknown

CMD

アクションのメタデータ ファイルで args を定義すると、args によって、Dockerfile で指定された CMD 命令がオーバーライドされます。 詳細については、「GitHub Actions のメタデータ構文」を参照してください。

Dockerfile で CMD を使用する場合は、次のガイドラインに従ってください。

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

サポートされているLinuxの機能

GitHub Actionsは、DockerがサポートするデフォルトのLinuxの機能をサポートします。 機能の追加や削除はできません。 Docker でサポートされる既定の Linux 機能の詳細については、Docker ドキュメントの「Linux カーネル機能」を参照してください。 Linux 機能の詳細については、Linux の man ページの "Linux 機能の概要" に関するページを参照してください。