TypeScript で GitHub Actions ワークフローを記述する「ghats」の紹介
GitHub Actions ワークフローを TypeScript で記述できるツールを作りました。
なぜなら GitHub Actions ワークフローは TypeScript で記述できた方がいいので。
import { Workflow, Job } from "ghats";
const workflow = new Workflow("Hello", {
on: "push",
});
workflow.addJob(
new Job("hello", {
runsOn: "ubuntu-latest",
})
.uses("actions/checkout@v4", {
with: { "persist-credentials": "false" }
})
.run("echo 'Hello, world!'"),
);
export default workflow;
この記事では ghats を使用して GitHub Actions ワークフローを記述する基本的な使い方についてまとめます。
インストール
npm でインストールできます。
$ npm install -D ghats
基本的な使い方
前提として、 ghats によるワークフロー定義ファイルは .github/workflows/*.ts に作成します。
.github/
└── workflows/
└── example.ts
以下のワークフローは actions/checkout を呼び出したあとに echo を実行する例です。
書き方については GitHub Actions に慣れている人であれば細かい解説は不要だと思います。
// ghats から Workflow, Job を import
import { Workflow, Job } from "ghats";
// workflow を定義
const workflow = new Workflow("Hello", {
on: "push",
});
// job を定義
workflow.addJob(
new Job("hello", {
runsOn: "ubuntu-latest",
})
.uses("actions/checkout@v4", {
with: { "persist-credentials": "false" }
})
.run("echo 'Hello, world!'"),
);
// workflow を default export
export default workflow;
ghats によるワークフロー定義ファイルを作成した後に ghats build コマンドを実行すると、 YAML 形式のワークフロー定義ファイルがビルドされます。
$ npx ghats build
ビルドされたワークフロー定義ファイル
# DO NOT EDIT THIS FILE
# This file is automatically generated by ghats (https://www.npmjs.com/package/ghats)
# Edit the workflow in .github/workflows/example.ts instead, and run `ghats build` to update this file.
{"name":"Hello","on":"push","jobs":{"hello":{"runs-on":"ubuntu-latest","steps":[{"with":{"persist-credentials":"false"},"uses":"actions/checkout@v4"},{"run":"echo 'Hello, world!'"}]}}}
ビルドされたワークフロー定義ファイルは実際に GitHub Actions 上で動作します。
リモートアクションの型サポートを利用する
GitHub Actions では actions/checkout などをはじめとした様々なリモートアクションが利用できますが、 ghats はこれらを参照する際に型サポートを利用できます。
まずは利用するリモートアクションを指定して ghats install コマンドを実行します。
$ npx ghats install actions/checkout
リモートアクションをインストールすると ghats から action 関数が import できるようになります。この関数を使えばリモートアクションの型サポートを利用できます。
-import { Workflow, Job } from "ghats";
+import { Workflow, Job, action } from "ghats";
const workflow = new Workflow("Hello", {
on: "push",
});
workflow.addJob(
new Job("hello", {
runsOn: "ubuntu-latest",
})
- .uses("actions/checkout@v4", {
+ .uses(action("actions/checkout", {
with: { "persist-credentials": "false" }
- })
+ }))
.run("echo 'Hello, world!'"),
);
export default workflow;
参照するリモートアクションの補完
リモートアクションの inputs の型サポート
ちなみに、 ghats install コマンドが完了すると .github/workflows/ ディレクトリ内に actions.json と actions-lock.json が作成されます。
.github/
└── workflows/
├── actions.json
└── actions-lock.json
actions.json にはインストールしたリモートアクションのバージョンが記録され、 actions-lock.json にはそのコミット SHA が記録されます。
{
"actions/checkout": "v4.2.2"
}
{
"actions": {
"actions/checkout@v4.2.2": "11bd71901bbe5b1630ceea73d27597364c9af683"
}
}
action 関数はこれらのファイルを利用して、リモートアクションの参照をコミット SHA で固定します。そのため、ワークフロー定義内ではリモートアクションのバージョンを明示的に指定する必要がありません。
// ...
new Job("hello", {
runsOn: "ubuntu-latest",
})
// `actions/checkout@<VERSION>` のようにアクションのバージョンを指定していない！！
.uses(action("actions/checkout", {
with: { "persist-credentials": "false" }
}))
// ...
# ワークフロー定義ファイルをビルド
$ npx ghats build
# ビルドされたワークフロー（わかりやすくするために整形したもの）
jobs:
hello:
runs-on: ubuntu-latest
steps:
# `actions/checkout` がコミット SHA で参照されている！！
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
with:
persist-credentials: "false"
# ...
一般的に、 GitHub Actions でリモートアクションを参照する際は Git タグではなくコミット SHA を使用することが推奨されています。
リリースされたアクションバージョンのコミットSHAを使用するのが、安定性とセキュリティのうえで最も安全です。
# ❌ Git タグによる参照
- uses: actions/checkout@v4
- uses: actions/checkout@v4.2.2
# ⭕ コミット SHA による参照
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
とはいえ都度リモートアクションのコミット SHA を明示的に指定するのは非常に手間です。
ghats を使えばそれらも自動的に面倒を見てくれますし、且つ参照するリモートアクションを actions.json で一元管理できるのでとても楽になります。
それ以外の ghats の詳しい使い方については公式ドキュメントをご参照ください。
ちなみに ghats のリポジトリの GitHub Actions ワークフロー自体も ghats で記述されています。
Discussion