【GitHub公式】GitHub Actionsテンプレートの「typescript-action」を使ったGitHub Actions開発の方法とTips！
こんにちは、リテールアプリ共創部の戸田駿太です。
今回はGitHub公式が提供するGitHub Actionsテンプレートの「typescript-action」を利用してTypeScriptでGitHub Actionsを作成する方法を紹介します。
typescript-actionとは
GitHubが公式で提供しているTypeScript製のGitHub Actionテンプレートです。
GitHub Actions開発のスターターテンプレートとして利用できます。
typescript-actionのリポジトリ
今回のサンプルリポジトリ
ユースケース
基本的にはGitHub Actionsだけを扱うツールの開発に利用します。
例えば
- E2Eテスト
- APIのテスト
- バックアップのツール
などの開発しているアプリの補助的なツールとしての利用が良さそうです。
私は業務でドキュメント類のバックアップとドキュメントをNotebookLMに入力するためのファイル統合を自動化しました。
主な特徴
「typescript-action」の特徴は以下の通りです。
✅ TypeScriptをサポートしており型安全なGitHub Actions開発が可能
✅ PrettierやESLint、Jestなどのツールが最初からセットアップ済み
✅ CI/CDパイプラインが最初からセットアップ済み
✅ GitHub Actionsでよく利用するライブラリが標準搭載
要するに初期セットアップがとても簡単ということです。
typescript-actionの利用方法
今回はPublicリポジトリを作成して公開する方法を紹介します。
Privateリポジトリでは必要ない工程も含まれています。
リポジトリの作成
typescript-actionのリポジトリからリポジトリを作成します。
「Use this template」 →「Create a new repository」をクリックします。
自分のリポジトリ名を入力して、「Public」or「Private」を選択、「Create repository」をクリックしてリポジトリを作成します。
あとは作成したリポジトリをローカルにクローンして開発を始めるだけです。
セットアップ
「typescript-action」のREADMEに書いてある通りにセットアップをします。
まず行うのはCODEOWNERSファイルにあるオーナーを変更します。
あとはnpm installで依存パッケージをインストールして開発を進めましょう！
各コマンドの解説
「typescript-action」では以下のコマンドが用意されています。
専用機能のコマンド
| コマンド | 説明 |
|---|---|
format:write |
Prettierでコードを自動フォーマット |
format:check |
Prettierでコードフォーマットをチェック |
lint |
ESLintでコードの静的解析を実行 |
test |
Jestでテストを実行 |
ci-test |
CI環境用のテスト実行 |
coverage |
テストカバレッジバッジを生成してbadges/coverage.svgに出力 |
package |
TypeScriptコードをRollupでバンドル化 |
package:watch |
ファイル変更を監視してリアルタイムでバンドル化 |
local-action |
ローカル環境でActionをテスト実行 |
組み合わせ機能のコマンド
| コマンド | 説明 | 実行される処理 |
|---|---|---|
bundle |
コードフォーマット後にバンドル化を実行 | format:write → package |
all |
開発からリリースまでの必要なチェックを一括実行 | format:write → lint → test → coverage → package |
開発環境の説明
「typescript-action」では以下の開発環境が利用されています。
- Node.js: v24.8.0
- npm: v11.6.0
- TypeScript: v5.9.2
- ESLint: v9.35.0
- Jest: v30.1.3
- Rollup: v4.50.2
- Prettier: v3.6.2
各ツールの詳細解説
TypeScript設定
設定ファイル:
tsconfig.json- メインのTypeScript設定tsconfig.base.json- 基本設定tsconfig.eslint.json- ESLint用設定
ESLint
JS, TS, JEST, Prettierなどの基本ルールが適用されていて特に編集しなくても利用できます。
Jest
初期状態では__tests__ ディレクトリにあるテストを実行するようになっています。
カバレッジ機能が有効になっているのでテストのカバレッジ率が確認できます。
Rollup（バンドラー）
TypeScriptファイルを単一のJavaScriptファイルにバンドルするツールです。
バンドルされたファイルはdist/index.jsに出力されます。
初期状態のdist/index.jsはコミットする必要があります。そのためPR作成前には必ずバンドル化を実行してコミットしてください。
もしdistディレクトリをコミットしたくない場合は以下の方法が参考になります。
- Composite Actionでの実行時にバンドルするようにする
- Dockerなどのコンテナを利用する
このように方法はいくつかあるのですが、実行時間が長くなるデメリットがあります。
それを踏まえると初期状態のままで良いかもしれません。
Prettier（コードフォーマッター）
コードフォーマットを自動で行ってくれます。
コード自体のフォーマットはいいのですが、READMEに書く日本語には少し相性が悪いです。
# 日本語コンテンツ向けの推奨設定
printWidth: 100 # または120
proseWrap: preserve # または never
Dependabot
依存関係の自動更新を行うDependabotの設定が最初から含まれています。
.github/dependabot.ymlファイルで設定されており、npm パッケージとGitHub Actionsの両方の依存関係を自動で更新してくれます。
これにより、セキュリティアップデートや新機能を自動で取り込むことができ、メンテナンスの負担が大幅に軽減されます。
Local Action
ローカル環境でActionsをテスト実行することができます。
GitHub Actionsは基本的にGitHub上で実行されるため、ローカルで実行できるのは結構嬉しいですね！
ただ、その分コードの考慮する点が増えたり初期設定が難しくなるので、しっかりと業務利用などをする場合に利用するのが良さそうです。
サンプルの説明
今回説明するサンプルリポジトリ
機能
Hello World (hello-world)
カスタマイズ可能な挨拶メッセージを出力します。手動実行できます。
Daily Activity (daily-activity)
リポジトリの基本情報（リポジトリ名、オーナー、実行者など）を JSON 形式で出力します。毎日午前9時に自動実行されます。
Default（デフォルト）
指定した時間だけ待機する処理です。元のテンプレートの機能をそのまま残しています。
アーキテクチャ
このテンプレートを利用する際の私なりのアーキテクチャを紹介します。
ディレクトリ構造
srcディレクトリはこのようになっています。
workflowsディレクトリ内で各workflowが分離した構造にしています。
src/
├── index.ts # エントリーポイント
├── main.ts # デフォルト処理（消してもいい）
├── wait.ts # デフォルトの処理（消してもいい）
└── workflows/ # 新規追加
├── hello-world.ts # 追加したworkflow
└── daily-activity.ts # 追加したworkflow
エントリーポイントのindex.ts
エントリーポイントのindex.tsには全てのworkflowのルーティングを任せています。
エントリーポイントにindex.tsを利用する理由
index.tsでルーティングするメリットはバンドルした時のファイルサイズが小さくなることです。
先ほど説明した通りこのリポジトリではRollupを利用してバンドルしています。
もし各workflowのファイルに対してバンドルを行うと、バンドルしたファイルが複数作成されることになり、
共通で利用しているライブラリなどもバンドルされるため、ファイルのサイズが大きくなります。
さらにrollup.config.tsの設定を増やす必要があり運用面でも負担が増えます。
これらを防ぐためにindex.tsに全てのworkflowのルーティングを任せています。
Workflowのyamlファイル
workflowsディレクトリ内で各workflowが分離した構造にしています。（これは良くあるパターンですね）
先ほど説明したエントリーポイントにindex.tsを利用している都合上、それぞれのworkflowのyamlファイルにはWORKFLOW_TYPE: hello-worldを設定しています。
テスト
テストは__tests__ディレクトリに配置しています。
デフォルトの設定から変えていません。
ただ、こだわりはないので自由に変えてもいいと思います。
Local Action
Local Actionが標準搭載されているのがこのテンプレートの嬉しいところです。できるだけ使いたいですね。
Local Actionが全てのworkflowで利用できるようにコマンドを追加しています。
中には.envファイルを読み込む必要のあるworkflowがあるので、.envに必要な環境変数を設定してください。
CI/CDのパイプラインにもちゃんと設定しています。
全てのテストができるように配列にtest-case名を入れてループしています。
まとめ
typescript-actionの強みは初期セットアップの簡単さです！
とりあえずリポジトリをテンプレートから作成してすぐに開発に移れる手軽さが最高です！
ただ簡単にMVPで作成するときにはオーバースペックかもしれません。
そのような場合は、yamlとJSだけのリポジトリを作成して開発するのもいいですね。
実際触ってみたときに環境が整いすぎて最初にリポジトリの仕組みや利用しているツール類の理解に戸惑うこともありました。
その時の教訓と解決策をこのブログに書いてあるので参考にして試してみてください。
参考リンク
