Composite Action Template を作りました [GitHub Actions]
テンプレートリポジトリ
作成した Composite action のテンプレートです。
概要
GitHub Actions でアクションを自作する際に作成できるアクションには3種類あります。
- JavaScript (TypeScript)
- Docker container
- Composite
JavaScript, TypeScript, Docker container にはそれぞれ公式のテンプレートがあるのですが、なぜか Composite だけありません。
action.yml に直接コードを書くのでテストやビルド、デプロイ等の周辺コードが不要という判断なのかもしれませんが、さっと作るときに action.yml に何を書けばよかったっけ？と調べるところから始めるのは不便です。
そこでマーケットプレースに公開するのに必要な項目を網羅した action.yml と LICENSE や CODEOWNERS および README.md ファイルに加えてテストも（！）含めたテンプレートを作成しました。
Bash でテストを書くことはあまりないと思うので参考になると幸いです。
使い方
右上の Use this template （緑のボタン）を押すとこのテンプレートを元にリポジトリが作成できます。
必要に応じてファイルを編集すれば完成です。
詳細
action.yml
アクション本体です。
どの種類のアクションでも同じですがファイル名は action.yml でないといけません。
runs には using: composite を指定し steps にコードを書きます。
個々の詳細はドキュメントを参考に。 branding を忘れがち。
test.yml
Bash でも test コマンドを使ってテストを書くことができます。
終了ステータスが 0 または 1 で返るので if を噛まさずそのまま run ステップへ返します。
0 が成功 1 が失敗です。
- run: test "${GREET}" = "Hello World"
[ ], [[ ]], (( )) 等も使用できます。
[ ] と [[ ]] を単行で使用する場合は YAML としてパースされないように '' か "" で囲って文字列として扱う必要があるので注意してください。
- run: '[ "${GREET}" = "Hello World" ]'
- run: |
[ "${GREET}" = "Hello World" ]
アクションなので各 OS でテストできるよう strategy.matrix を使用して全 OS 分を並列で走らせます。
test コマンドが Bash でしか使えないので defaults.run には shell: bash を指定し PowerShell （や他のシェル）はサボっていますが、必要そうだったら足してあげてください。
PowerShell でも test コマンドが使用できるようなのでテストを追加しました。
ただ環境変数の書き方が違うので run は if: runner.os == 'Windows' などを使用して分ける必要があります。テンプレートでは Windows 環境でも bash のテストをしておきたかったので別のジョブにしました。
PowerShell のテストはこちらも参考にしてください。（test コマンドを使わない場合）
並列で大量に走らせると保護ブランチでのステータスチェックの指定が大変です。
そこで全てのテストが成功したときだけ test-passing を走らせて全体の結果としています。
このステータスが失敗になることはありませんが Required になっていれば未実行の場合もマージをブロックしてくれます。
アクションの内容によってはテストを書くのは難しいかもしれませんが少しでも書いてあると安心感が違うので出来る範囲で書いておきましょう。
もちろん Bash にこだわる必要はありませんのでお好きな言語で書いても大丈夫です。
README.md にバッジも表示されてるようになっています。
README.md
テンプレートの使い方が書いてあります。
この記事と似たような内容です。
中身は丸っと削除して作成しているアクション用に書き換えます。
（他のアクションテンプレートに倣ってテンプレートの使い方だけ書いてますがアクション用の README のベースにできるものも別途あった方がいいような）
→ README のベースとなるように変更したので記事を書きました
Usage, Inputs, Outputs, Environments, Contributions などの情報があると良さそうです。
あまり見かけませんが Support OS や Support Events の項目もあった方がよさそうです。
License は右上の About に表示されるようになったのでライセンスファイルさえ用意していれば README.md には不要な気がしています。
せっかくテストがあるのでバッジも表示しておきましょう。
CODEOWNERS
コードオーナーという仕組みがあります。
設定しておくとレビュワーに自動でアサインされたり保護ブランチでコードオーナーのレビューを必須にできたりします。
コードオーナーが PR の作成者だった場合はそのままマージできます。
dependabot.yml
Dependabot の設定ファイルです。
テストで使用している GitHub Actions のアップデートを行います。
必要に応じて変更してください。
LICENSE
MIT ライセンスです。
必要に応じて変更してください。
アクションを作る際の注意
忘れがちですがセルフホストランナーや Enterprise を考慮して作成しましょう。
GitHub ホストランナーに依存したパスの使用を避けたり、 API のベース URL には GITHUB_API_URL や GITHUB_GRAPHQL_URL を使用します。
Composite action に限らず他の種類のアクションでも同様です。
マーケットプレースへ公開
リリースの作成時にマーケットプレースへ公開するか聞かれますので指示に従って設定します。
実例
テンプレートを使用して実際にアクションを作成してみました。
git config の user.name と user.email を自動設定するだけの簡単なアクションです。
これくらいだと1時間もかからず作れるのでみなさんも作ってみてはいかがでしょうか。
Discussion