ドキュメントには頻繁に更新が加えられ、その都度公開されています。本ページの翻訳はまだ未完成な部分があることをご了承ください。最新の情報については、英語のドキュメンテーションをご参照ください。本ページの翻訳に問題がある場合はこちらまでご連絡ください。

JavaScript アクションを作成する

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

GitHub ActionsはGitHub Free、GitHub Pro、GitHub Team、GitHub Enterprise Cloud、GitHub Oneで利用できます。 GitHub Actions is not available for private repositories owned by accounts using legacy per-repository plans. 詳しい情報については「GitHubの製品」を参照してください。

ここには以下の内容があります:

はじめに

In this guide, you'll learn about the basic components needed to create and use a packaged JavaScript action. To focus this guide on the components needed to package the action, the functionality of the action's code is minimal. The action prints "Hello World" in the logs or "Hello [who-to-greet]" if you provide a custom name.

This guide uses the GitHub Actions Toolkit Node.js module to speed up development. 詳しい情報については、actions/toolkit リポジトリ以下を参照してください。

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

To ensure your JavaScript actions are compatible with all GitHub-hosted runners (Ubuntu, Windows, and macOS), the packaged JavaScript code you write should be pure JavaScript and not rely on other binaries. JavaScript actions run directly on the runner and use binaries that already exist in the virtual environment.

Self-hosted runners must have Node.js installed to run JavaScript actions. For more information about the requirements of self-hosted runners, see "About self-hosted runners."

必要な環境

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

  1. Node.js 12.x をダウンロードして、インストールします。npm も Node.js 12.x に含まれています。

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

  2. GitHub に新しいリポジトリを作成します。 リポジトリ名は任意です。この例のように "hello-world-javascript-action" を使ってもいいでしょう。 これらのファイルは、プロジェクトを GitHubにプッシュした後で追加できます。 詳しい情報については、「新しいリポジトリの作成」を参照してください。

  3. リポジトリをお手元のコンピューターにクローンします。 詳しい情報についてはリポジトリのクローンを参照してください。

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

    cd hello-world-javascript-action
  5. ターミナルから、package.jsonファイルでディレクトリを初期化します。

    npm init -y

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

hello-world-javascript-actionディレクトリに、以下のサンプルコードで新しく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: 'node12'
  main: 'index.js'

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

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

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

The toolkit @actions/core package provides an interface to the workflow commands, input and output variables, exit statuses, and debug messages.

このツールキットはまた、認証を受けたOctokit RESTクライアント及びGitHub Actionsコンテキストへのアクセスを返す@actions/githubパッケージも提供します。

ツールキットは、coregithub パッケージ以外のものも提供しています。 詳しい情報については、actions/toolkit リポジトリ以下を参照してください。

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

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 と名付けた新しいファイルを追加してください。

index.js

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パッケージを使ってメッセージをログに記録し、失敗の終了コードを設定します。 For more information, see "Setting exit codes for actions."

README の作成

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

hello-world-javascript-action ディレクトリの中に、以下の情報を指定した README.md ファイルを作成してください。

  • アクションが実行する内容の詳細
  • 必須の入力引数と出力引数
  • オプションの入力引数と出力引数
  • アクションが使用するシークレット
  • アクションが使用する環境変数
  • ワークフローでアクションを使う使用方法の例

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

uses: actions/hello-world-javascript-action@v1
with:
  who-to-greet: 'Mona the Octocat'

アクションの GitHub へのコミットとタグ、プッシュ

GitHub が、動作時にワークフロー内で実行される各アクションをダウンロードし、コードの完全なパッケージとして実行すると、ランナーマシンを操作するためのrun などのワークフローコマンドが使えるようになります。 つまり、JavaScript コードを実行するために必要なあらゆる依存関係を含める必要があります。 アクションのリポジトリに、ツールキットの core および github パッケージをチェックインする必要があります。

ターミナルから、action.ymlindex.jsnode_modulespackage.jsonpackage-lock.json、および README.md ファイルをコミットします。 node_modules を一覧表示する .gitignore ファイルを追加した場合、node_modules ディレクトリをコミットするため、その行を削除する必要があります。

アクションのリリースにはバージョンタグを加えることもベストプラクティスです。 アクションのバージョニングに関する詳しい情報については「アクションについて」を参照してください。

git add action.yml index.js node_modules/* package.json package-lock.json README.md
git commit -m "My first action is ready"
git tag -a -m "My first action release" v1
git push --follow-tags

node_modules ディレクトリをチェックインする代わりに、zeit/ncc というツールを使って、コードやモジュールを配信用に使う 1 つのファイルにコンパイルできます。

  1. ターミナルで次のコマンドを実行し、zeit/ncc をインストールします: npm i -g @zeit/ncc

  2. 次のコマンドで、index.js ファイルをコンパイルします: ncc build index.js

    コードの書かれた、新しい dist/index.js ファイルと、コンパイルされたモジュールが表示されます。

  3. 新しい dist/index.js ファイルを利用するため、次のコマンドで action.ymlmain キーワードを変更します: main: 'dist/index.js'

  4. すでに node_modules ディレクトリをチェックインしていた場合、次のコマンドで削除します: rm -rf node_modules/*

  5. ターミナルから、action.ymldist/index.js、および node_modules ファイルをコミットします。

    git add action.yml dist/index.js node_modules/*
    git commit -m "Use zeit/ncc"
    git tag -a -m "My first action release" v1
    git push --follow-tags

ワークフローでアクションを試す

これで、ワークフローでアクションをテストできるようになりました。 プライベートリポジトリにあるアクションは、同じリポジトリのワークフローでしか使用できません。 パブリックアクションは、どのリポジトリのワークフローでも使用できます。

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

次のワークフローコードでは、actions/hello-world-javascript-action というリポジトリにある完全な hello world アクションを使っています。 ワークフローコードを .github/workflows/main.yml ファイルにコピーし、actions/hello-world-javascript-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-javascript-action@v1
      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:
      # このリポジトリのプライベートアクションを使うには、リポジトリをチェックアウトしなければならない
      - 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 入力に指定した名前とタイムスタンプがログに出力されます。

ワークフローでアクションを使用しているスクリーンショット

担当者にお尋ねください

探しているものが見つからなかったでしょうか?

弊社にお問い合わせください