Docker コンテナーのアクションを作成する

はじめに

このガイドでは、パッケージ化されたDockerコンテナのアクションを作成して使うために必要な、基本的コンポーネントについて学びます。 アクションのパッケージ化に必要なコンポーネントのガイドに焦点を当てるため、アクションのコードの機能は最小限に留めます。 このアクションは、ログに "Hello World" を出力するものです。また、カスタ� 名を指定した� �合は、"Hello [who-to-greet]" を出力します。

このプロジェクトを完了すると、あなたの Docker コンテナのアクションをビルドして、ワークフローでテストする方法が理解できます。

セルフホストランナーでDockerコンテナアクションを実行するためには、Linuxオペレーティングシステ� を使い、Dockerがインストールされていなければなりません。 セルフホステッド ランナーの要件の詳細については、「セルフホステッド ランナーについて」を参照してく� さい。

前提条件

GitHub Actionsの環境変数及びDockerコンテナのファイルシステ� に関する基本的な理解があれば役立つでしょう。

• "環境変数の使用"
• 「GitHub ホステッド ランナーについて」

始める前に、GitHub リポジトリを作成する必要があります。

1. に新しいリポジトリを作成します。 リポジトリ名は任意です。この例のように "hello-world-docker-action" を使ってもいいでしょう。 詳細については、「新しいリポジトリの作成」を参照してく� さい。

2. リポジトリをお手元のコンピューターにクローンします。 詳細については、「リポジトリをクローンする」を参照してく� さい。

3. ターミナルから、ディレクトリを新しいリポジトリに変更します。

   Shell

   cd hello-world-docker-action

Dockerfileの作成

新しい hello-world-docker-action ディレクトリに、新しい Dockerfile ファイルを作成します。 問題が発生する� �合は、ファイル名で大文字が正しく使用されていることを確認します (D は大文字にしますが、f は大文字にしません)。 詳細については、「GitHub Actions のための Dockerfile サポート」を参照してく� さい。

Dockerfile

# Container image that runs your code
FROM alpine:3.10

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

# Code file to execute when the docker container starts up (`entrypoint.sh`)
ENTRYPOINT ["/entrypoint.sh"]

アクションのメタデータファイルの作成

上で作成した hello-world-docker-action ディレクトリに新しい action.yml ファイルを作成します。 詳細については、「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 出力パラメーターが定義されています。 入力を Docker コンテナーに渡すには、inputs を使用して入力を宣言し、args キーワードで入力を渡す必要があります。 args に含めたすべてのものがコンテナーに渡されますが、アクションのユーザーにわかりやすいよう、inputs を使用することをお勧めします。

GitHub によって Dockerfile からイメージがビルドされ、このイメージを使用して新しいコンテナーでコマンドが実行されます。

アクションのコードの記述

任意のベース Docker イメージを選択できるので、アクションに任意の言語を選択できます。 次のシェル スクリプトの例では、who-to-greet 入力変数を使って、ログ ファイルに "Hello [who-to-greet]" と出力されます。

次に、スクリプトは現在の時刻を取得し、それをジョブ内で後に実行するアクションが利用できる出力変数に設定します。 GitHub に出力変数を認識させるには、echo "::set-output name=<output name>::<value>" という構文でワークフロー コマンドを使う必要があります。 詳細については、「GitHub Actions のワークフロー コマンド」を参照してく� さい。

1. hello-world-docker-action ディレクトリに新しい entrypoint.sh ファイルを作成します。

2. 次のコードを entrypoint.sh ファイルに追� します。

   entrypoint.sh

   Shell

   #!/bin/sh -l
   
   echo "Hello $1"
   time=$(date)
   echo "::set-output name=time::$time"

   entrypoint.sh がエラーなしで実行された� �合、アクションの状態は success に設定されます。 アクションのコード中で明示的に終了コードを設定して、アクションのステータスを提供することもできます。 詳細については、「アクションの終了コードの設定」を参照してく� さい。

3. 次のコマンドをシステ� で実行して、entrypoint.sh ファイルを実行可能にします。

   Shell

   $ chmod +x entrypoint.sh

READMEの作成

アクションの使用方法を説明するために、README ファイルを作成できます。 README はアクションの公開を計画している時に非常に役立ちます。また、アクションの使い方をあなたやチー� が覚えておく方法としても優れています。

hello-world-docker-action ディレクトリに、次の情� �を指定する README.md ファイルを作成します。

• アクションの動作に関する詳細な説明。
• 必� �の入力および出力の引数。
• 省略可能な入力および出力の引数。
• アクションで使用されるシークレット。
• アクションで使用される環境変数。
• ワークフローでのアクションの使用方法の例。

README.md

# Hello world docker action

This action prints "Hello World" or "Hello" + the name of a person to greet to the log.

## Inputs

## `who-to-greet`

**Required** The name of the person to greet. Default `"World"`.

## Outputs

## `time`

The time we greeted you.

## Example usage

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

ワークフローでアクションをテストする

これで、ワークフローでアクションをテストできるようになりました。 アクションがプライベート リポジトリ内にある� �合、そのアクションは同じリポジトリ内のワークフローでのみ使用できます。 パブリック アクションは、任意のリポジトリ内のワークフローで使用できます。

パブリックアクションを使用する例

次のワークフロー コードでは、パブリックの 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'
      # Use the output from the `hello` step
      - 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 }}"

リポジトリから [アクション] タブをクリックして、最新のワークフロー実行を選択します。 [ジョブ] または視覚化グラフで、"A job to say hello" をクリックします。 "Hello Mona the Octocat" または who-to-greet 入力に使用した名前と、ログに出力されたタイ� スタンプが表示されます。