注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
はじめに
このガイドでは、パッケージ化されたDockerコンテナのアクションを作成して使うために必要な、基本的コンポーネントについて学びます。 アクションのパッケージ化に必要なコンポーネントのガイドに焦点を当てるため、アクションのコードの機能は最小限に留めます。 このアクションは、ログに "Hello World" を出力するものです。また、カスタム名を指定した場合は、"Hello [who-to-greet]" を出力します。
このプロジェクトを完了すると、あなたの Docker コンテナのアクションをビルドして、ワークフローでテストする方法が理解できます。
セルフホストランナーでDockerコンテナアクションを実行するためには、Linuxオペレーティングシステムを使い、Dockerがインストールされていなければなりません。 セルフホステッド ランナーの要件の詳細については、「自己ホスト ランナーの概要」を参照してください。
警告: ワークフローとアクションを作成するときは、コードが攻撃者からの信頼されていない入力を実行する可能性があるかどうかを常に考慮する必要があります。 攻撃者が悪意あるコンテンツを挿入してくるかもしれないので、特定のコンテキストは信頼できない入力として扱うべきです。 詳しくは、「GitHub Actions のセキュリティ強化」を参照してください。
前提条件
- GitHub にリポジトリを作成し、ワークステーションに複製する必要があります。 詳細については、「新しいリポジトリの作成」および「リポジトリをクローンする」を参照してください。
- リポジトリで Git LFS を使用する場合は、リポジトリのアーカイブにオブジェクトを含める必要があります。 詳しくは、「リポジトリのアーカイブで Git LFS オブジェクトを管理する」を参照してください。
- GitHub Actions の環境変数及びDockerコンテナのファイルシステムに関する基本的な理解があれば役立つでしょう。 詳細については、「変数に情報を格納する」および「GitHub ホステッド ランナーの使用」を参照してください。
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"]
# 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 }}
# 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 が出力変数を認識するには、それらを$GITHUB_OUTPUT
環境ファイルecho "<output name>=<value>" >> $GITHUB_OUTPUT
に書き込む必要があります。 詳しくは、「GitHub Actions のワークフロー コマンド」を参照してください。
-
hello-world-docker-action
ディレクトリに新しいentrypoint.sh
ファイルを作成します。 -
次のコードを
entrypoint.sh
ファイルに追加します。entrypoint.sh
Shell #!/bin/sh -l echo "Hello $1" time=$(date) echo "time=$time" >> $GITHUB_OUTPUT
#!/bin/sh -l echo "Hello $1" time=$(date) echo "time=$time" >> $GITHUB_OUTPUT
entrypoint.sh
がエラーなしで実行された場合、アクションの状態はsuccess
に設定されます。 アクションのコード中で明示的に終了コードを設定して、アクションのステータスを提供することもできます。 詳しくは、「アクションの終了コードの設定」を参照してください。 -
entrypoint.sh
ファイルを実行可能にします。 Git では、クローンやフォークがあるたびにリセットされないように、ファイルのアクセス許可モードを明示的に変更する方法が用意されています。Shell git add entrypoint.sh git update-index --chmod=+x entrypoint.sh
git add entrypoint.sh git update-index --chmod=+x entrypoint.sh
-
必要に応じて、Git インデックス内のファイルのアクセス許可モードを確認するには、次のコマンドを実行します。
Shell git ls-files --stage entrypoint.sh
git ls-files --stage entrypoint.sh
100755 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 0 entrypoint.sh
のような出力は、ファイルに実行可能なアクセス許可があることを意味します。 この例では、755
が実行可能なアクセス許可を示しています。
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@v2 with: who-to-greet: 'Mona the Octocat'
# 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@v2
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
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
ワークフローでアクションをテストする
これで、ワークフローでアクションをテストできるようになりました。
- アクションがプライベート リポジトリにある場合は、アクセスできるユーザーを制御できます。 詳細については、「リポジトリの GitHub Actions の設定を管理する」を参照してください。 - アクションが内部リポジトリにある場合は、アクセスできるユーザーを制御できます。 詳細については、「リポジトリの GitHub Actions の設定を管理する」を参照してください。
- パブリック アクションは、任意のリポジトリ内のワークフローで使用できます。
注: GitHub Enterprise Server の GitHub Actions には、GitHub.com または GitHub Marketplace に対するアクションへのアクセスが制限される場合があります。 詳細については、「GitHub.com からのアクションへのアクセスを管理する」を参照し、GitHub Enterprise のサイト管理者に問い合わせてください。
パブリックアクションを使用する例
次のワークフロー コードでは、パブリックの 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@v2 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 }}"
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@v2
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@v4 - 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 }}"
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@v4
- 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 world action step をクリックすると、"Hello Mona the Octocat" またはログに出力されている who-to-greet
に入力した名前が表示されます。 タイムスタンプを表示するには、 [出力時刻の取得] をクリックします。
コンテナー アクションで作成したファイルへのアクセス
コンテナー アクションを実行する、ランナーの既定の作業ディレクトリ (GITHUB_WORKSPACE
) がコンテナー上の /github/workspace
ディレクトリに自動的にマップされます。 コンテナーのこのディレクトリに追加されたファイルは、同じジョブ内の後続のステップで使用できます。 たとえば、プロジェクトをビルドするコンテナー アクションがあり、ビルド出力を成果物としてアップロードする場合は、次の手順を使用できます。
workflow.yml
jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 # Output build artifacts to /github/workspace on the container. - name: Containerized Build uses: ./.github/actions/my-container-action - name: Upload Build Artifacts uses: actions/upload-artifact@v3 with: name: workspace_artifacts path: ${{ github.workspace }}
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
# Output build artifacts to /github/workspace on the container.
- name: Containerized Build
uses: ./.github/actions/my-container-action
- name: Upload Build Artifacts
uses: actions/upload-artifact@v3
with:
name: workspace_artifacts
path: ${{ github.workspace }}
ビルド出力を成果物としてアップロードする方法の詳細については、[ワークフローからのデータの格納と共有]を参照してください。
GitHub.com
に対する Docker コンテナー アクションの例
Docker コンテナー アクションの例は、GitHub.com に多数あります。