GitHub スクリプトとは
このユニットでは、GitHub Actions ワークフローで GitHub スクリプトを使って一般的な GitHub プロセスを自動化する方法について学びます。
GitHub スクリプトとは
GitHub スクリプトは、認証済みの Octokit クライアントを提供し、JavaScript をワークフロー ファイル内で直接記述できるようにするアクションです。 それは Node.js 内で実行されるため、スクリプトを記述するときにそのプラットフォームの機能を利用できます。
Octokit とは
Octokit は GitHub API 用クライアントの公式のコレクションです。 これらのクライアントの 1 つである rest.js を使うと、JavaScript で GitHub の REST インターフェイスにアクセスできます。
octokit/rest.js を使用して GitHub API を自動化することは常に可能でしたが、適切に設定して管理することは面倒な場合があります。 GitHub スクリプトを使用する大きな利点の 1 つは、このオーバーヘッドがすべてそれによって処理されるため、API の使用をすぐに開始できることです。 依存関係、構成、認証について案じる必要はありません。
octokit/rest.js でできること
簡単に答えると、GitHub の自動化に関しては事実上何でもできます。 コミット、pull request、issue へのアクセスに加えて、ユーザー、プロジェクト、organization にもアクセスできます。 一般的に使用されるファイル (一般的なライセンスや .gitignore ファイルなど) の一覧を取得できます。 Markdown をレンダリングすることもできます。
GitHub を統合するものを作成している場合、求めているものが octokit/rest.js の完全なドキュメントで見つかることがよくあります。
GitHub スクリプトを使用するのと octokit/rest.js との違い
使用方法の主な違いは、GitHub スクリプトでは github という名前の事前認証済み octokit/rest.js クライアントが提供されることです。
つまり、
octokit.issues.createComment({
の代わりに以下を使います
github.issues.createComment({。
github 変数に加えて次の変数も用意されています。
-
contextは、ワークフロー実行のコンテキストを含むオブジェクトです。 -
coreは、 @actions/コア パッケージへの参照です。 -
ioは、 @actions/io パッケージへの参照です。
GitHub スクリプトを使うワークフローの作成
GitHub スクリプト アクションは、他のアクションと同様にワークフローに適合します。 その結果、既存のワークフロー (CI/CD 用に既に設定済みのものなど) と混在させることさえできます。 GitHub スクリプトの便利さを示すため、それを使って、新しく作成されたすべての issue へのコメントを自動的に投稿する完全なワークフローを構築します。
最初に、name と on 句を使って、issue が開かれたらワークフローを実行することを指定します。
name: Learning GitHub Script
on:
issues:
types: [opened]
次に、Linux で一連のステップを実行する comment という名前のジョブを定義します。
jobs:
comment:
runs-on: ubuntu-latest
steps:
この場合、GitHub スクリプト アクションという 1 つのステップしかありません。
- uses: actions/github-script@0.8.0
with:
github-token: ${{secrets.GITHUB_TOKEN}}
script: |
github.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: "🎉 You've created this issue comment using GitHub Script!!!"
})
GitHub Actions を使用すると、リポジトリで発生するイベントの自動化に非常に役立ちます。 リポジトリ ビジターが重大なバグに関する情報を含む新しい問題を開いたとします。 バグに気付かせてくれるのはありがたいことかもしれませんが、リポジトリに訪れるユーザーが増えると、この単純なタスクでも手に負えなくなる可能性があります。 issue のコメントを自動的に行うと、訪問者に毎回感謝するプロセスを自動化できます。
actions/github-script@0.8.0 の使用
actions/github-script@0.8.0 アクション (GitHub スクリプトとも呼ばれます) によって、GitHub API との統合のための困難な作業がすべて行われます。
このアクションには、要求が認証されるように、実行時に提供される github-token が必要です。 これは自動的に行われるため、そのコードをそのまま使用できます。
script パラメーターは、事実上、github に格納されている octokit/rest/js クライアントを使用する任意の JavaScript にすることができます。 この場合は、ハードコーディングされたコメントを作成する 1 行のみです (読みやすくするために複数行に分割されています)。
ワークフローの実行後、GitHub スクリプトは、[Actions] タブで確認できるように実行したコードをログに記録します。
別のファイルからの実行
GitHub スクリプトのシナリオを満たすために、大量のコードを使う必要がある場合があります。 そのような場合は、スクリプトを別のファイルに保持し、すべてのスクリプトをインラインで作成するのではなく、ワークフローから参照できます。
その手法を使う簡単なワークフローの例を次に示します。
on: push
jobs:
echo-input:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/github-script@v2
with:
script: |
const path = require('path')
const scriptPath = path.resolve('./path/to/script.js')
console.log(require(scriptPath)({context}))