JavaScript アクションを作成する

はじめに

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

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

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

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

前提条件

開始する前に、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 のメタデータ構文」をご覧ください。

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: dist/index.js

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: dist/index.js

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

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

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

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

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

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

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

npm install @actions/core @actions/github

npm install @actions/core @actions/github

node_modules ディレクトリと、インストールされている依存関係とそのバージョンを追跡する package-lock.json ファイルが表示されます。 node_modules ディレクトリをリポジトリにコミットしないでください。

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

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

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

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

import * as core from "@actions/core";
import * as github from "@actions/github";

try {
  // `who-to-greet` input defined in action metadata file
  const nameToGreet = core.getInput("who-to-greet");
  core.info(`Hello ${nameToGreet}!`);

  // Get the current time and set it as an output variable
  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);
  core.info(`The event payload: ${payload}`);
} catch (error) {
  core.setFailed(error.message);
}

import * as core from "@actions/core";
import * as github from "@actions/github";

try {
  // `who-to-greet` input defined in action metadata file
  const nameToGreet = core.getInput("who-to-greet");
  core.info(`Hello ${nameToGreet}!`);

  // Get the current time and set it as an output variable
  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);
  core.info(`The event payload: ${payload}`);
} catch (error) {
  core.setFailed(error.message);
}

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

READMEの作成

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

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

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

# Hello world JavaScript 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

```yaml
uses: actions/hello-world-javascript-action@e76147da8e5c81eaf017dede5645551d4b94427b
with:
  who-to-greet: Mona the Octocat
```

# Hello world JavaScript 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

```yaml
uses: actions/hello-world-javascript-action@e76147da8e5c81eaf017dede5645551d4b94427b
with:
  who-to-greet: Mona the Octocat
```

アクションのコミット、タグ付け、プッシュ

GitHub を使うと、実行時にワークフローで実行される各アクションをダウンロードし、コードの完全なパッケージとして実行できます。その後は、run などのワークフロー コマンドを使ってランナー マシンを操作できるようになります。 つまり、JavaScript コードを実行するために必要なあらゆる依存関係を含める必要があります。 たとえば、このアクションでは @actions/core と @actions/github パッケージが使われます。

node_modules ディレクトリをチェックインすると、問題が発生する可能性があります。 別の方法として、rollup.js や @vercel/ncc などのツールを使って、配布用の 1 つのファイルにコードと依存関係を結合できます。

1. ターミナルで次のコマンドを実行して、rollup とそのプラグインをインストールします。

   npm install --save-dev rollup @rollup/plugin-commonjs @rollup/plugin-node-resolve

2. 次のコードを使って、リポジトリのルートに rollup.config.js という名前の新しいファイルを作成します。

   JavaScript

   import commonjs from "@rollup/plugin-commonjs";
   import { nodeResolve } from "@rollup/plugin-node-resolve";
   
   const config = {
     input: "src/index.js",
     output: {
       esModule: true,
       file: "dist/index.js",
       format: "es",
       sourcemap: true,
     },
     plugins: [commonjs(), nodeResolve({ preferBuiltins: true })],
   };
   
   export default config;
   

3. ご利用の dist/index.js ファイルをコンパイルします。

   rollup --config rollup.config.js

   ご自分のコードとすべての依存関係を含む新しい dist/index.js ファイルが表示されます。

4. ターミナルから更新をコミットします。

   Shell

   git add src/index.js dist/index.js rollup.config.js package.json package-lock.json README.md action.yml
   git commit -m "Initial commit of my first action"
   git tag -a -m "My first action release" v1.1
   git push --follow-tags
   

コードをコミットしてプッシュすると、更新されたリポジトリは次のようになります。

hello-world-javascript-action/
├── action.yml
├── dist/
│   └── index.js
├── package.json
├── package-lock.json
├── README.md
├── rollup.config.js
└── src/
    └── index.js

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

これで、ワークフローでアクションをテストできるようになりました。

パブリック アクションは、任意のリポジトリ内のワークフローで使用できます。 アクションがプライベート リポジトリまたは内部 リポジトリ内にある場合、リポジトリ設定は、同じリポジトリ内でのみ、または同じ 組織またはエンタープライズ が所有する他のリポジトリでもアクションが可能かどうかによって決まります。 詳しくは、「リポジトリの GitHub Actions の設定を管理する」をご覧ください。

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

この例では、外部リポジトリ内から新しいパブリック アクションを実行する方法を示します。

次の YAML を .github/workflows/main.yml にある新しいファイルにコピーし、ユーザー名と上記で作成したパブリック リポジトリの名前で uses: octocat/hello-world-javascript-action@1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b 行を更新します。 who-to-greet 入力を自分の名前に置き換えることもできます。

on:
  push:
    branches:
      - main

jobs:
  hello_world_job:
    name: A job to say hello
    runs-on: ubuntu-latest

    steps:
      - name: Hello world action step
        id: hello
        uses: octocat/hello-world-javascript-action@1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
        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:
    branches:
      - main

jobs:
  hello_world_job:
    name: A job to say hello
    runs-on: ubuntu-latest

    steps:
      - name: Hello world action step
        id: hello
        uses: octocat/hello-world-javascript-action@1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
        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 }}"

このワークフローがトリガーされると、ランナーによってパブリック リポジトリから hello-world-javascript-action アクションがダウンロードされ、そして実行されます。

プライベートアクションを使用する例

ワークフロー コードをアクションのリポジトリ内の .github/workflows/main.yml ファイルにコピーします。 who-to-greet 入力を自分の名前に置き換えることもできます。

on:
  push:
    branches:
      - main

jobs:
  hello_world_job:
    name: A job to say hello
    runs-on: ubuntu-latest

    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:
    branches:
      - main

jobs:
  hello_world_job:
    name: A job to say hello
    runs-on: ubuntu-latest

    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 に入力した名前が表示されます。 タイムスタンプを表示するには、 [出力時刻の取得] をクリックします。

JavaScript アクションを作成するためのテンプレート リポジトリ

GitHub には、JavaScript および TypeScript アクションを作成するためのテンプレート リポジトリが用意されています。 これらのテンプレートを使い、テスト、リンティング、その他の推奨プラクティスなど、新しいアクションの作成をすぐに始められます。

• javascript-action テンプレート リポジトリ
• typescript-action テンプレート リポジトリ

GitHub.com

に対する JavaScript アクションの例

JavaScript のアクション例は、GitHub.com に多数あります。

• DevExpress/testcafe-action
• duckduckgo/privacy-configuration