注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
はじめに
このガイドでは、パッケージ化されたJavaScriptのアクションを作成して使うために必要な、基本的コンポーネントについて学びます。 アクションのパッケージ化に必要なコンポーネントのガイドに焦点を当てるため、アクションのコードの機能は最小限に留めます。 このアクションは、ログに "Hello World" を出力するものです。また、カスタ� 名を指定した� �合は、"Hello [who-to-greet]" を出力します。
このガイドでは、開発の速度を高めるためにGitHub Actions ToolkitのNode.jsモジュールを使います。 詳細については、actions/toolkit リポジトリを参照してく� さい。
このプロジェクトを完了すると、あなたの JavaScript コンテナのアクションをビルドして、ワークフローでテストする方法が理解できます
JavaScriptのアクションがGitHubがホストするすべてのランナー(Ubuntu、Windows、macOS)と互換性があることを保証するためには、作成するパッケージ化されたJacScriptのコードは純粋なJavaScriptであり、他のバイナリに依存していてはなりません。 JavaScript のアクションはランナー上で直接実行され、ランナー イメージ内に既に存在するバイナリを利用します。
警告: ワークフローとアクションを作成するときは、コードが攻撃者からの信� �されていない入力を実行する可能性があるかどうかを常に考慮する必要があります。 攻撃者が悪意あるコンテンツを挿入してくるかもしれないので、特定のコンテキストは信� �できない入力として扱うべきです。 詳細については、「スクリプト インジェクションのリスクについて」を参照してく� さい。
前提条件
開始する前に、Node.jsをダウンロードし、パブリック GitHub リポジトリを作成する必要があります。
-
npm を含む Node.js 12.x をダウンロードしてインストールします。
-
your GitHub Enterprise Server instance 上に新しいパブリック リポジトリを作成し、それを "hello-world-javascript-action" と呼びます。 詳細については、「新しいリポジトリの作成」を参照してく� さい。
-
リポジトリをお手元のコンピューターにクローンします。 詳細については、「リポジトリをクローンする」を参照してく� さい。
-
ターミナルから、ディレクトリを新しいリポジトリに変更します。
Shell cd hello-world-javascript-action
-
ターミナルから、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: 'node12'
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
パッケージをインストールします。
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
という名前の新しいファイルを追� します。
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
パッケージを使用してメッセージをログに記録し、失敗した終了コードを設定します。 詳細については、アクションの終了コードの設定に関するページを参照してく� さい。
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@v1.1
with:
who-to-greet: 'Mona the Octocat'
```
アクションの GitHub へのコミットとタグ、プッシュ
GitHub Enterprise Server が、動作時にワークフロー内で実行される各アクションをダウンロードし、コードの完全なパッケージとして実行すると、ランナーマシンを操作するための run
などのワークフローコマンドが使えるようになります。 つまり、JavaScript コードを実行するために必要なあらゆる依存関係を含める必要があります。 ツールキットの core
および github
パッケージをご利用のアクションのリポジトリにチェックインする必要があります。
ご利用のターミナルから、action.yml
、index.js
、node_modules
、package.json
、package-lock.json
、README.md
の各ファイルをコミットします。 .gitignore
が一覧されている node_modules
ファイルを追� した� �合は、その行を削除して、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.1
git push --follow-tags
node_modules
ディレクトリをチェックインすると、問題が発生する可能性があります。 別の方法として、@vercel/ncc
というツールを使用して、配布に使用する 1 つのファイルに、コードとモジュールをコンパイルできます。
-
ターミナルで次のコマンドを実行して、
vercel/ncc
をインストールします。npm i -g @vercel/ncc
-
ご利用の
index.js
ファイルをコンパイルします。ncc build index.js --license licenses.txt
ご利用のコードを含む新しい
dist/index.js
ファイルと、コンパイルされたモジュールが表示されます。 また、使用しているnode_modules
のすべてのライセンスを含む添付のdist/licenses.txt
ファイルも表示されます。 -
新しい
dist/index.js
ファイルを利用するため、action.yml
ファイルのmain
キーワードを変更します。main: 'dist/index.js'
-
node_modules
ディレクトリに既にチェックインしている� �合は、それを削除します。rm -rf node_modules/*
-
ご利用のターミナルから、更新プログラ� を自分の
action.yml
、dist/index.js
、node_modules
ファイルにコミットします。
git add action.yml dist/index.js node_modules/*
git commit -m "Use vercel/ncc"
git tag -a -m "My first action release" v1.1
git push --follow-tags
ワークフローでアクションをテストする
これで、ワークフローでアクションをテストできるようになりました。 アクションがプライベート リポジトリ内にある� �合、そのアクションは同じリポジトリ内のワークフローでのみ使用できます。 パブリック アクションは、任意のリポジトリ内のワークフローで使用できます。
注: の GitHub Actions では、GitHub.com または GitHub Marketplace に対するアクションへのアクセスが制限される� �合があります。 詳細については、「GitHub.com からのアクションへのアクセスを管理する」を参照し、GitHub Enterprise サイト管理者にお問い合わせく� さい。
パブリックアクションを使用する例
この例では、外部リポジトリ内から新しいパブリック アクションを実行する方法を示します。
次の YAML を .github/workflows/main.yml
にある新しいファイルにコピーし、ユーザー名と上記で作成したパブリック リポジトリの名前で uses: octocat/hello-world-javascript-action@v1.1
行を更新します。 who-to-greet
入力を自分の名前に置き換えることもできます。
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: octocat/hello-world-javascript-action@v1.1
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
入力を自分の名前に置き換えることもできます。
.github/workflows/main.yml
on: [push]
jobs:
hello_world_job:
runs-on: ubuntu-latest
name: A job to say hello
steps:
# To use this repository's private action,
# you must check out the repository
- 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'
# 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 Mona the Octocat" または who-to-greet
入力に使用した名前と、ログに出力されたタイ� スタンプが表示されます。
JavaScript アクションを作成するためのテンプレート リポジトリ
GitHub には、JavaScript および TypeScript アクションを作成するためのテンプレート リポジトリが用意されています。 これらのテンプレートを使い、テスト、リンティング、その他の推奨プラクティスなど、新しいアクションの作成をすぐに始められます。