JavaScript アクションを作成する

このガイドでは、アクションツールキットを使って JavaScript アクションをビルドする方法について学びます。

この記事の内容

はじめに

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

このガイドでは、開発の速度を高めるためにGitHub Actions ToolkitのNode.jsモジュールを使います。 詳細については、actions/toolkit リポジトリを参照してください。

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

JavaScriptのアクションがGitHubがホストするすべてのランナー（Ubuntu、Windows、macOS）と互換性があることを保証するためには、作成するパッケージ化されたJavaScriptのコードは純粋なJavaScriptであり、他のバイナリに依存していてはなりません。 JavaScript のアクションはランナー上で直接実行され、ランナー イメージ内に既に存在するバイナリを利用します。

Warning

ワークフローとアクションを作成するときは、攻撃者によってコードが信頼されていない入力を実行する可能性があるかどうかを常に考慮する必要があります。 攻撃者が悪意あるコンテンツを挿入してくるかもしれないので、特定のコンテキストは信頼できない入力として扱うべきです。 詳しくは、「GitHub Actions のセキュリティ強化」をご覧ください。

前提条件

開始する前に、Node.jsをダウンロードし、パブリック GitHub リポジトリを作成する必要があります。

  1. Node.js 20.x (これには、npm も含まれます) をダウンロードしてインストールします。

    https://nodejs.org/en/download/

  2. GitHub 上に新しいパブリック リポジトリを作成し、それを "hello-world-javascript-action" と呼びます。 詳しくは、「新しいリポジトリの作成」をご覧ください。

  3. リポジトリをお手元のコンピューターにクローンします。 詳しくは、「リポジトリをクローンする」をご覧ください。

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

    Shell
    cd hello-world-javascript-action

  5. ターミナルから、npm を使用してディレクトリを初期化し、package.json ファイルを生成します。

    Shell
    npm init -y

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

次のコード例を使用して、action.yml という名前の新しいファイルを hello-world-javascript-action ディレクトリに作成します。 詳しくは、「GitHub Actions のメタデータ構文」をご覧ください。

YAML
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: 'node20'
  main: 'index.js'

このファイルによって、who-to-greet 入力と time 出力が定義されます。 また、アクションのランナーに対して、この JavaScript アクションの実行を開始する方法を伝えています。

アクションツールキットのパッケージの追加

アクションのツールキットは、Node.js パッケージのコレクションで、より一貫性を保ちつつ、JavaScript を素早く作成するためのものです。

ツールキット @actions/core パッケージには、ワークフロー コマンド、入力および出力変数、終了ステータス、デバッグ メッセージに対するインターフェイスが用意されています。

また、このツールキットには、認証済み Octokit REST クライアントおよびアクセスを GitHub Actions のコンテキストに返す @actions/github パッケージも用意されています。

このツールキットは、core および github パッケージ以外のものも備えています。 詳細については、actions/toolkit リポジトリを参照してください。

ご利用のターミナルで、アクション ツールキットの core および github パッケージをインストールします。

Shell
npm install @actions/core
npm install @actions/github

これで、node_modules ディレクトリと先ほどインストールしたモジュール、package-lock.json ファイルとインストールしたモジュールの依存関係、およびインストールした各モジュールのバージョンが表示されるはずです。

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

このアクションは、ツールキットを使って、アクションのメタデータ ファイルに必要な who-to-greet 入力変数を取得し、ログのデバッグメッセージに "Hello [who-to-greet]" を出力します。 次に、スクリプトは現在の時刻を取得し、それをジョブ内で後に実行するアクションが利用できる出力変数に設定します。

GitHub Actions は、webhook イベント、Git ref、ワークフロー、アクション、およびワークフローをトリガーした人に関するコンテキスト情報を提供します。 コンテキスト情報にアクセスするために、github パッケージを利用できます。 あなたの書くアクションが、webhook イベントペイロードをログに出力します。

次のコードを含む index.js という名前の新しいファイルを追加します。

JavaScript
const core = require('@actions/core');
const github = require('@actions/github');

try {
  // `who-to-greet` input defined in action metadata file
  const nameToGreet = core.getInput('who-to-greet');
  console.log(`Hello ${nameToGreet}!`);
  const time = (new Date()).toTimeString();
  core.setOutput("time", time);
  // Get the JSON webhook payload for the event that triggered the workflow
  const payload = JSON.stringify(github.context.payload, undefined, 2)
  console.log(`The event payload: ${payload}`);
} catch (error) {
  core.setFailed(error.message);
}

上記の index.js の例でエラーがスローされた場合、core.setFailed(error.message); では、アクション ツールキットの @actions/core パッケージを使用してメッセージをログに記録し、失敗した終了コードを設定します。 詳しくは、「