ノート: GitHubホストランナーは、現在GitHub Enterprise Serverでサポートされていません。 GitHubパブリックロードマップで、計画されている将来のサポートに関する詳しい情� �を見ることができます。
はじめに
このガイドでは、パッケージ化されたDockerコンテナのアクションを作成して使うために必要な、基本的コンポーネントについて学びます。 アクションのパッケージ化に必要なコンポーネントのガイドに焦点を当てるため、アクションのコードの機能は最小限に留めます。 このアクションは、ログに "Hello World" を出力するものです。また、カスタ� 名を指定した� �合は、"Hello [who-to-greet]" を出力します。
このプロジェクトを完了すると、あなたの Docker コンテナのアクションをビルドして、ワークフローでテストする方法が理解できます。
セルフホストランナーでDockerコンテナアクションを実行するためには、Linuxオペレーティングシステ� を使い、Dockerがインストールされていなければなりません。 セルフホストランナーに対する要求に関する詳しい情� �については「セルフホストランナーについて」を参照してく� さい。
警告: ワークフローやアクションを作る際には、攻撃者からの信� �できない入力をコードが実行するかもしれないことを、常に意識しなければなりません。 攻撃者が悪意あるコンテンツを挿入してくるかもしれないので、特定のコンテキストは信� �できない入力として扱うべきです。 詳しい情� �については「スクリプトインジェクションのリスクを理解する」を参照してく� さい。
必要な環境
GitHub Actionsの環境変数及びDockerコンテナのファイルシステ� に関する基本的な理解があれば役立つでしょう。
始める前に、GitHub リポジトリを作成する必要があります。
-
GitHub Enterprise Serverインスタンス に新しいリポジトリを作成します。 リポジトリ名は任意です。この例のように "hello-world-docker-action" を使ってもいいでしょう。 詳しい情� �については、「新しいリポジトリの作成」を参照してく� さい。
-
リポジトリをお手元のコンピューターにクローンします。 詳しい情� �についてはリポジトリのクローンを参照してく� さい。
-
ターミナルから、ディレクトリを新しいリポジトリに変更します。
Shell cd hello-world-docker-action
Dockerfileの作成
新しいhello-world-docker-action
ディレクトリ内に、新たにDockerfile
というファイルを作成してく� さい。 Make sure that your filename is capitalized correctly (use a capital D
but not a capital f
) if you're having issues. 詳しい情� �については、「GitHub Actions のための Dockerfile サポート」を参照してく� さい。
Dockerfile
# コードを実行するコンテナイメージ
FROM alpine:3.10
# アクションのリポジトリからコードファイルをコンテナのファイルシステ� パス `/`にコピー
COPY entrypoint.sh /entrypoint.sh
# dockerコンテナが起動する際に実行されるコードファイル (`entrypoint.sh`)
ENTRYPOINT ["/entrypoint.sh"]
アクションのメタデータファイルの作成
新しい action.yml
ファイルを、上で作成した hello-world-docker-action
ディレクトリの中に作成します。 詳しい情� �については、「GitHub Actions のメタデータ構文」を参照してく� さい。
action.yml
# action.yml
name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
who-to-greet: # id of input
description: 'Who to greet'
required: true
default: 'World'
outputs:
time: # id of output
description: 'The time we greeted you'
runs:
using: 'docker'
image: 'Dockerfile'
args:
- ${{ inputs.who-to-greet }}
このメタデータは、1 つの who-to-greet
入力と 1 つの time
出力パラメータを定義しています。 To pass inputs to the Docker container, you should declare the input using inputs
and pass the input in the args
keyword. Everything you include in args
is passed to the container, but for better discoverability for users of your action, we recommended using inputs.
GitHub は Dockerfile
からイメージをビルドし、このイメージを使用して新しいコンテナでコマンドを実行します。
アクションのコードの記述
任意のベース Docker イメージを選択できるので、アクションに任意の言語を選択できます。 次のシェルスクリプトの例では、who-to-greet
入力変数を使って、ログファイルに "Hello [who-to-greet]" と出力します。
次に、スクリプトは現在の時刻を取得し、それをジョブ内で後に実行するアクションが利用できる出力変数に設定します。 GitHubに出力変数を認識させるには、echo "::set-output name=<output name>::<value>"
という構文でワークフローコマンドを使わなければなりません。 詳しい情� �については「GitHub Actionsのワークフローコマンド」を参照してく� さい。
-
hello-world-docker-action
ディレクトリに、新しいentrypoint.sh
を作成します。 -
entrypoint.sh
ファイルに次のコードを追� します。entrypoint.sh
Shell #!/bin/sh -l echo "Hello $1" time=$(date) echo "::set-output name=time::$time"
entrypoint.sh
がエラーなく実行できたら、アクションのステータスはsuccess
に設定されます。 アクションのコード中で明示的に終了コードを設定して、アクションのステータスを提供することもできます。 詳しい情� �については「アクションの終了コードの設定」を参照してく� さい。 -
以下のコマンドをシステ� で実行して、
entrypoint.sh
ファイルを実行可能にしてく� さい。Shell $ chmod +x entrypoint.sh
READMEの作成
アクションの使用方法を説明するために、README ファイルを作成できます。 README はアクションの公開を計画している時に非常に役立ちます。また、アクションの使い方をあなたやチー� が覚えておく方法としても優れています。
hello-world-docker-action
ディレクトリの中に、以下の情� �を記述した README.md
ファイルを作成してく� さい。
- アクションが実行する内容の詳細
- 必� �の入力引数と出力引数
- オプションの入力引数と出力引数
- アクションが使用するシークレット
- アクションが使用する環境変数
- ワークフローでアクションを使う使用方法の例
README.md
# Hello world docker action
このアクションは"Hello World"もしくは"Hello" + ログに挨拶する人物名を出力します。
## Inputs
## `who-to-greet`
**Required** The name of the person to greet. デフォルトは `"World"`。
## Outputs
## `time`
The time we greeted you.
## 使用例
uses: actions/hello-world-docker-action@v1
with:
who-to-greet: 'Mona the Octocat'
アクションのGitHub Enterprise Serverへのコミットとタグ、プッシュ
ターミナルから、action.yml
、entrypoint.sh
、Dockerfile
、および README.md
ファイルをコミットします。
アクションのリリースにはバージョンタグを� えることもベストプラクティスです。 アクションのバージョン管理の詳細については、「アクションについて」を参照してく� さい。
git add action.yml entrypoint.sh Dockerfile README.md
git commit -m "My first action is ready"
git tag -a -m "My first action release" v1
git push --follow-tags
ワークフローでアクションをテストする
これで、ワークフローでアクションをテストできるようになりました。 プライベートリポジトリにあるアクションは、同じリポジトリのワークフローでしか使用できません。 パブリックアクションは、どのリポジトリのワークフローでも使用できます。
Note: GitHub Actions on GitHub Enterprise Serverインスタンス may have limited access to actions on GitHub.com or GitHub Marketplace. For more information, see "Managing access to actions from GitHub.com" and contact your GitHub Enterprise site administrator.
パブリックアクションを使用する例
以下のワークフローのコードは、パブリックのactions/hello-world-docker-action
リポジトリ内の完成したhello worldアクションを使います。 次のワークフローサンプルコードを .github/workflows/main.yml
にコピーし、actions/hello-world-docker-action
をあなたのリポジトリとアクション名に置き換えてく� さい。 who-to-greet
の入力を自分の名前に置き換えることもできます。
.github/workflows/main.yml
on: [push]
jobs:
hello_world_job:
runs-on: ubuntu-latest
name: A job to say hello
steps:
- name: Hello world action step
id: hello
uses: actions/hello-world-docker-action@v1
with:
who-to-greet: 'Mona the Octocat'
# `hello` ステップからの出力を使用する
- name: Get the output time
run: echo "The time was ${{ steps.hello.outputs.time }}"
プライベートアクションを使用する例
次のワークフローコードサンプルを、あなたのアクションのリポジトリの .github/workflows/main.yml
ファイルにコピーします。 who-to-greet
の入力を自分の名前に置き換えることもできます。
.github/workflows/main.yml
on: [push]
jobs:
hello_world_job:
runs-on: ubuntu-latest
name: A job to say hello
steps:
# To use this repository's private action,
# you must check out the repository
- name: Checkout
uses: actions/checkout@v2
- name: Hello world action step
uses: ./ # Uses an action in the root directory
id: hello
with:
who-to-greet: 'Mona the Octocat'
# Use the output from the `hello` step
- name: Get the output time
run: echo "The time was ${{ steps.hello.outputs.time }}"
リポジトリから [Actions] タブをクリックして、最新のワークフロー実行を選択します。 Under Jobs or in the visualization graph, click A job to say hello. "Hello Mona the Octocat"、またはwho-to-greet
入力に指定した名前とタイ� スタンプがログに出力されます。