カスタム GitHub アクションを作成する
GitHub Actions は、独自の使い慣れた便利なリポジトリにあるすべての要素をコードからクラウドに移行する際に役立つ強力な機能です。 ここでは、さまざまな種類の GitHub アクションと、カスタム GitHub アクションを作成するためのメタデータ、構文、ワークフロー コマンドについて説明します。
GitHub アクションの種類
アクションは、開発ワークフローのカスタマイズに使用できる個々のタスクです。 独自のアクションは、リポジトリと対話するカスタム コードを記述してカスタム タスクを実行するか、GitHub コミュニティで共有されているアクションを使用することで作成できます。 さまざまなアクションを見てみると、"Docker コンテナーのアクション"、"JavaScript のアクション"、および "複合実行ステップのアクション" の 3 種類のアクションがあることがわかります。 それぞれのアクションの種類について詳しく見ていきましょう。
Docker コンテナーのアクション
Docker コンテナーでは、GitHub Actions のコードにより環境がパッケージ化されます。 つまり、すべての依存関係がそのコンテナー内にあるため、このアクションは一貫性のある信頼性の高い環境で実行されます。 アクションを特定の環境構成で実行する必要がある場合は、オペレーティング システムとツールをカスタマイズできるため、Docker コンテナーを使用することをお勧めします。 ジョブでコンテナーを構築し、取得する必要があるため、Docker コンテナーのアクションは JavaScript のアクションよりも遅くなることが多いという欠点があります。
Docker コンテナーのアクションを構築するには、環境変数と Docker コンテナーのファイルシステムの使用方法に関する基本的な知識が必要です。 次に示すような、いつくかの簡単な手順を実行することで、Docker コンテナーのアクションを構築することができます。
Dockerfileを作成し、Docker イメージをアセンブルするコマンドを定義します。action.ymlメタデータ ファイルを作成し、アクションの入力と出力を定義します。 ファイルで、runs: using:の値をdockerに、runs: image:の値をDockerfileに設定します。entrypoint.shファイルを作成し、Docker イメージについて説明します。- アクションをコミットし、
action.yml、entrypoint.sh、Dockerfile、README.mdなどのファイルを使用して GitHub にプッシュします。
JavaScript のアクション
JavaScript のアクションは、ランナーのマシンで直接実行できます。また、アクションの実行に使用する環境からアクション コードを分離することができます。 このため、アクション コードは単純化され、Docker コンテナー内のアクションよりも迅速に実行できます。
パッケージ化された JavaScript のアクションを作成して使用するための前提条件として、npm を含む Node.js をダウンロードする必要があります。 オプションの手順ですが、GitHub Actions Toolkit Node.js を使用することをお勧めします。これは Node.js パッケージのコレクションであり、より一貫性のある JavaScript のアクションをすばやく構築することができます。
JavaScript アクションを構築する手順は最小限の簡単なものです。
action.ymlメタデータ ファイルを作成してアクションの入力と出力を定義し、この JavaScript アクションの実行を開始する方法をアクション ランナーに知らせます。index.jsファイルを作成し、Toolkit パッケージ、ルーティング、およびアクションの他の機能に関するコンテキスト情報を含めます。- アクションをコミットし、
action.yml、index.js、node_modules、package.json、package-lock.json、README.mdなどのファイルを使用して GitHub にプッシュします。
複合実行ステップのアクション
複合実行ステップのアクションでは、シェル スクリプトを使用してアクションを再利用できます。 同じアクション内で、複数のシェル言語を混在させることもできます。 複数のタスクを自動化するためのシェル スクリプトが多数ある場合は、それらを簡単にアクションに変換し、異なるワークフローで再利用できます。 JavaScript を使用したり、Docker コンテナーでコードをラップしたりするよりも、シェル スクリプトを記述する方が簡単な場合があります。
アクションの作成に必要なメタデータと構文
GitHub アクションを作成または確認する際には、最初に action.yml ファイルを確認して、アクションに必要な入力、出力、説明、実行、その他の構成情報を評価します。 これらのパラメーターの一部は必須ですが、それ以外は省略可能です。 action.yml ファイルでは、アクションに関する次の情報を定義します。
| パラメーター | Description | 必須 |
|---|---|---|
| 名前 | アクションの名前。 ジョブのアクションを視覚的に特定するのに役立ちます。 | はい |
| 説明 | アクションの内容の概要。 | はい |
| 入力 | 入力パラメーターでは、実行時にアクションで使用するデータを指定できます。 これらのパラメーターは、ランナーの環境変数になります。 | no |
| 出力 | 出力パラメーターでは、これらの出力を定義するアクションが実行された後に、ワークフローの後続のアクションで使用できるデータを指定できます。 | no |
| 実行 | アクションの実行時に実行するコマンド。 | はい |
| ブランド化 | アクションをカスタマイズして、GitHub Marketplace で識別するためのバッジを作成する際に使用する色と機能アイコン。 | no |
入力
入力は、実行時にアクションで使用することが予想されるデータを指定できるパラメーターです。 GitHub では、これらの入力パラメーターは環境変数として格納されます。
アクションの入力のリスト例を以下に示します。 firstNameStudent の入力は省略可能ですが、studentGrade の入力は必須です。
inputs:
firstNameStudent:
description: 'First name of student'
required: false
default: '1'
studentGrade:
description: 'Grade of the student'
required: true
出力
出力は、データを宣言することができるパラメーターです。 ワークフローで後から実行されるアクションでは、前に実行されたアクションで宣言された出力データを使用できることに注意してください。
以下に、学生の平均的な成績を宣言する簡単な出力の例を示します。
outputs:
average:
description: 'The average grade of the students'
実行
これまでに学んだように、アクションには、アクションの実行に必要なコマンドを定義する runs ステートメントが必要です。 アクションの作成方法 (Docker コンテナー、JavaScript、複合実行ステップのどれを使用するか) に応じて、runs 構文の定義が異なります。
Docker アクションの runs
Docker コンテナーのアクションでは、Docker アクションで次の引数で使用されるイメージを runs ステートメントで構成する必要があります。
using: Docker コンテナー アクションを実行するには、dockerに設定する必要がありますimage: アクションを実行するコンテナーとして使用される Docker イメージ
runs:
using: 'docker'
image: 'Dockerfile'
JavaScript のアクションの runs
JavaScript のアクションでは、runs ステートメントで次の 2 つの引数を取る必要があります。
using:mainで定義されている、コードの実行に使用されるアプリケーションmain: アクション コードを含むファイル。usingで定義されているアプリケーションではこのファイルが実行されます
たとえば、Node.js を使用した JavaScript アクションの runs ステートメントは以下のようになります。
runs:
using: 'node12'
main: 'main.js'
複合実行ステップのアクションの runs
複合実行ステップのアクションでは、runs ステートメントで次の 3 つの引数を取る必要があります。
using: 複合実行ステップを実行するには、"composite"に設定する必要がありますsteps: アクションを実行する実行ステップsteps[*].run: 実行するコマンド (インライン、またはアクション リポジトリ内のスクリプトにすることができます)
たとえば、ファイルパス /test/script/sh のスクリプトを実行する複合実行ステップのアクションの runs ステートメントは次のようになります。
runs:
using: "composite"
steps:
- run: ${{ github.action_path }}/test/script.sh
shell: bash
ブランド化
オプションの役立つ機能に、アクションのバッジのカスタマイズ機能があります。 バッジは、GitHub Marketplace のアクション名の横に表示されます。 色と機能アイコンを使用してバッジを作成できます。 ブランド化するには、使用するアイコンと色を指定する必要があります。
branding:
icon: 'shield'
color: 'blue'
以下に、GitHub Marketplace でのチェックアウト アクションのバッジ例を示します。
ワークフロー コマンド
ステップに適したアクションを見つけることができれば、ワークフローは簡単に作成できます。 場合によっては、必要な結果を得るために独自のアクションを作成する必要がありますが、ワークフロー コマンドを使用することで、ワークフローをさらにカスタマイズすることができます。
ワークフロー コマンドを使用すると、GitHub Actions ランナー マシンと通信できます。そのためには、書式設定されたテキスト行をコンソールに出力します。 これらのワークフロー コマンドは、シェル コマンドと使用することも、カスタム アクション内で使うこともできます。 ワークフロー コマンドを使用すると、ワークフロー ステップ間での情報の共有、デバッグやエラー メッセージのコンソールへの出力、環境変数の設定、出力パラメーターの設定、システム パスへの追加などを実行できて便利です。
ほとんどのワークフロー コマンドでは、次の特定の形式の echo コマンドが使用されます。その他のコマンドはファイルに書き込むことによって呼び出すことができます。
echo "::workflow-command parameter1={data},parameter2={data}::{command value}"
以下に、デバッグ メッセージ、情報メッセージ、エラー メッセージ、または警告メッセージをコンソールに出力する際の基本的なメッセージ ログの例をいくつか示します。
- name: workflow commands logging messages
run: |
echo "::debug::This is a debug message"
echo "This is an info message"
echo "::error::This is an error message"
echo "::warning::This is a warning message"
また、エラーが発生したファイルの名前 (file)、行番号 (line)、および列番号 (col) を使用して、ログに出力するメッセージを作成することもできます。 警告メッセージは黄色の強調表示で "warning" というテキストと共に示され、エラー メッセージは赤い強調表示で "error" というテキストと共に示されます。
echo "::error file=app.js,line=10,col=15::Something went wrong"
これらのワークフロー コマンドは 1 つの行に配置する必要があることに注意してください。 解析を妨げる文字 (コンマや改行など) は、URL エンコードする必要があります。
たとえば、次のテキストは複数行のメッセージです。
This text spans
across multiple lines
このメッセージは、ここに示すようにエンコードする必要があります。
This text spans%0Aacross multiple lines
ワークフロー コマンドに加えて、終了コードを設定してアクションの状態を設定することもできます。 これは、ワークフローでジョブを操作している際には、エラー終了コードによってすべての同時アクションが停止し、以降のアクションがキャンセルされるため重要です。 JavaScript アクションを作成する場合は、アクション ツールキット @actions/core パッケージを使用してメッセージをログに記録し、エラー終了コードを設定できます。 Docker コンテナー アクションを作成する場合は、entrypoint.sh スクリプトにエラー終了コードを設定できます。