先日, papix/action-cache-s3という, GitHub Actionsのactionを作ったというエントリを書きました.
このエントリでは, このactionを作るにあたって得た知見について, 雑に記しておきます.
actionの雛形
折角なので, TypeScriptでactionを書いてみようと思った訳ですが, 何と公式からTypeScript用の雛形が提供されています. 余程の理由がなければこれを使うと良いでしょう.
...今回, これを使うにあたって初めて知ったのですが, ｢Use this template｣なるボタン(機能)が存在していて, これをクリックするとそのリポジトリを雛形にして新しいリポジトリをシュッと作ることができるのですね.
というわけで, ボタンを押すと...
こういう感じでリポジトリの作成画面に遷移します. あとはリポジトリ名など指定して｢Create repository from template｣をクリックすればOKです.
ローカルでの実行
actionを実装するにあたり, 動作確認を実際にGitHub Actionsで実行するのではなく, 手元のマシンで実行したいと思うはずです. 改修を加える度にcommitして, pushして, 動作を確認する... というのはとても手間です.
そういった際に気になるのが, actionを実装するにあたって利用可能なツールキットであるところのactions/toolkitが提供する, core.getInputやcore.getStateで取得できるinput/stateを, 手元の環境で指定できるのか...? という点です.
これが出来れば, 例えばTypeScriptのテンプレートを使って実装しているactionであれば, ts-nodeなどを使ってローカルで動作確認をすることができそうです.
結論としては,
のドキュメントにあるように, core.getInputについてはINPUT_をprefixにした環境変数で, core.getStateについては, STATE_をprefixにした環境変数で, それぞれ指定できることができます.
例えば, 環境変数INPUT_SAMPLEをtest-inputとしてts-nodeなどでactionを手元で実行すると, core.getInput('SAMPLE')はtest-inputを返します.
また, 環境変数STATE_SAMPLEをtest-stateとしてactionを手元で実行すると, 今度はcore.getState('SAMPLE')はtest-stateを返してくれます.
これで, 余程の事がなければ, GitHub Actionsのactionは手元のマシンで開発し, 動作確認ができると思います.
バージョニング
GitHub Actionsのためのactionのバージョニングについては, 以下のドキュメントが参考になります.
掻い摘んで説明すると... まず, actionをワークフローで(usesによって)利用する場合, どのバージョンを利用するかを指定しなければなりません.
例えば, GitHub公式のactions/cacheのExample workflowを見てみると, 次のように v1 を指定しています.
- name: Cache Primes id: cache-primes uses: actions/cache@v1 with: path: prime-numbers key: ${{ runner.os }}-primes
このバージョンニングは, 実態としてはGitのrefを利用しています. 例えば, actions/cache@v1を指定した場合, actions/cache リポジトリにある v1 というタグを参照することになります.
従って, やろうと思えば次のようにshaを直接指定したり, ブランチ名を指定することも可能です(なお, ここでは例としてpapix/sample-actionという架空のactionを開発しているとします).
steps:
- uses: papix/sample-action@41775a4da8ffae865553a738ab8ac1cd5a3c0044
- uses: papix/sample-action@master
actionを開発している際, 別のリポジトリで動作を試したい! という時は, これらの方法でバージョン指定すると良さそうです.
但し, このようにmasterブランチを指定することについては, 先程紹介したドキュメントにおいて,
Warning: do not reference master since that is the latest code and can be carrying breaking changes of the next major version.
と記載されています. ｢そりゃそうだ｣という感じではありますが, masterを指定していると常に最新のactionが利用されることになり, 意図しない変更が含まれる可能性があるので, 基本的にはmasterを参照しないようにしましょう.
...閑話休題. ここまでの話を振り返ると, GitHub Actionsのactionを開発するにあたって, バージョニングは適切なタグを付与することで実現していることがわかります.
例えば, 今開発しているpapix/sample-actionの先頭のcommitをv1.0.0として指定するのであれば, 次のようにしてv1.0.0タグを付与し, それをpushします. そうすると, ワークフローにおいて papix/sample-action@v1.0.0 としてactionを利用できるようになります.
$ git tag v1.0.0 $ git push origin v1.0.0
注意点としては, v1.0.0のタグだけを付与している時, ワークフローにおいて papix/sample-action@v1 というバージョンを指定してactionを利用することはできません.
つまり, ワークフローでactionを利用するとき, そのバージョン指定はあくまでrefに従っていて, v1.* の最新のものを v1 として扱う... といった処理は, GitHub Actionsには存在しません.
そこで, 次のようにv1.0.0に加えて, 別途v1のタグを付与し, pushしてあげる必要があります.
$ git tag v1 $ git push origin v1
更に, この後に幾つかcommitを重ねて新しいバージョン(例えばv1.0.1)をリリース(= タグを付与してpush)した場合, v1 がそれを指すように上書きする必要があります(既に存在するv1タグを上書きするので, -f/--forceオプションが必要です).
$ git tag --force v1 $ git push origin v1 --force
会社で教えてもらった情報ですが, この辺りのバージョニングをGitHub ActionsでよしなにやってくれるGitHub Actionsのactionもあります. 必要に応じて利用を検討してみても良いでしょう.
まとめ
というわけで, 備忘録を兼ねてpapix/action-cache-s3を作る時に得た知見などをまとめました. GitHub Actionsはとにかく便利ですが, 自分でactionを作ることで更に便利することができるので, 良いアイデアがあればactionを作ってみては如何でしょうか.
