ノート: 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パブリックロードマップで、計画されている将来のサポートに関する詳しい情報を見ることができます。
はじめに
このガイドでは、パッケージ化された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
というファイルを作成してください。 詳しい情報については、「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
出力パラメータを定義しています。 Docker コンテナに入力を渡すには、inputs
を使用して入力を宣言したうえで args
キーワードを使用します。
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
ワークフローでアクションをテストする
これで、ワークフローでアクションをテストできるようになりました。 プライベートリポジトリにあるアクションは、同じリポジトリのワークフローでしか使用できません。 パブリックアクションは、どのリポジトリのワークフローでも使用できます。
ノート: 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@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:
# このリポジトリのプライベートアクションを使用するには
# リポジトリをチェックアウトする
- 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'
# 「hello」ステップの出力を使用する
- name: Get the output time
run: echo "The time was ${{ steps.hello.outputs.time }}"
リポジトリから [Actions] タブをクリックして、最新のワークフロー実行を選択します。 "Hello Mona the Octocat"、または who-to-greet
入力に指定した名前とタイムスタンプがログに出力されます。