GitHub Actions ワークフローを TypeScript で記述できるツールを作りました。
なぜなら GitHub Actions ワークフローは TypeScript で記述できた方がいいので。
.github/workflows/example.ts
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 でインストールできます。
前提として、 ghats によるワークフロー定義ファイルは .github/workflows/*.ts に作成します。
.github/
└── workflows/
└── example.ts
以下のワークフローは actions/checkout を呼び出したあとに echo を実行する例です。
書き方については GitHub Actions に慣れている人であれば細かい解説は不要だと思います。
.github/workflows/example.ts
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 によるワークフロー定義ファイルを作成した後に ghats build コマンドを実行すると、 YAML 形式のワークフロー定義ファイルがビルドされます。
.github/workflows/example.yml
{"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 できるようになります。この関数を使えばリモートアクションの型サポートを利用できます。
.github/workflows/example.ts
-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 が記録されます。
.github/workflows/actions.json
{
"actions/checkout": "v4.2.2"
}
.github/workflows/actions-lock.json
{
"actions": {
"actions/checkout@v4.2.2": "11bd71901bbe5b1630ceea73d27597364c9af683"
}
}
action 関数はこれらのファイルを利用して、リモートアクションの参照をコミット SHA で固定します。そのため、ワークフロー定義内ではリモートアクションのバージョンを明示的に指定する必要がありません。
.github/workflows/example.ts
new Job("hello", {
runsOn: "ubuntu-latest",
})
.uses(action("actions/checkout", {
with: { "persist-credentials": "false" }
}))
.github/workflows/example.yml
jobs:
hello:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
with:
persist-credentials: "false"
一般的に、 GitHub Actions でリモートアクションを参照する際は Git タグではなくコミット SHA を使用するのが推奨されています。
リリースされたアクションバージョンのコミットSHAを使用するのが、安定性とセキュリティのうえで最も安全です。
- uses: actions/checkout@v4
- uses: actions/checkout@v4.2.2
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
とはいえ都度リモートアクションのコミット SHA を明示的に指定するのは非常に手間です。
ghats を使えばそれらも自動的に面倒を見てくれますし、且つ参照するリモートアクションを actions.json で一元管理できるのでとても楽になります。
それ以外の ghats の詳しい使い方については公式ドキュメントをご参照ください。
ちなみに ghats のリポジトリの GitHub Actions ワークフロー自体も ghats で記述されています。
Be the first to comment
