Github Actionsの公式レファレンスの歩き方
きっかけ
仕事で9ヶ月ほどGithub Actionsを触るようになり，細かいTipsが身につきました．同僚がGithub Actionsをこれから触るということで，Github Actionsの公式レファレンスの歩き方(読み方)を書いていこうと思います．
というのも，Github ActionsはDomain Specificな用語の使い方が多く慣れないとうまく情報を探せないのです．使い始めた当時はちょっと苦労したので(ネットの先人が残してくれた様々なノウハウに感謝！！)，公式レファレンスをどう読んでいったら良いのかをまとめておこうと思います．
要約
- Github Actionsのレファレンスを読むときはEnglishで！
- Github Actionsの基本的な使い方が知りたくなったら...
Workflow syntax for GitHub Actions - ワイルドカードの書き方を知りたくなったら...
Workflow syntax for GitHub Actions#filter-pattern-cheat-sheet - 処理の中でGithub Actionsのメタ情報を使いたくなったら...
Contexts
Expressions
Environment variables - Github Actionsのトリガーイベントから得られる情報を使いたくなったら...
Webhook events and payloads - Github Actionsの実行結果画面をカスタマイズしたくなったら...
Workflow commands for GitHub Actions - ステップやワークフローを跨いで値を使いたくなったら...
Workflow commands for GitHub Actions#setting-an-output-parameter - Githubから追加で情報を取りたいと思ったら...
GitHub REST API
Github Actionsのレファレンスを読むときはEnglishで！
これは，意外と大事だと思っている点．レファレンスというドキュメントというものは「本文を上から読んでいく」のではなく「検索して該当箇所を見つける」「目次から欲しい情報に飛ぶ」という使い方をするものだと思います．前者の場合は日本語でも英語でも大した差はないですが，実は日本語だと後者は使えません (目次のリンクを自動生成する時のベースが英語htmlのままのためと思われる)．そのため日本語でドキュメントを読もうと思うと大変不便です．ぜひ公式レファレンスの言語設定は英語にしておきましょう．
Github Actionsの基本的な使い方が知りたくなったら...
おそらく，初めてGithub Actionsを使うとなった場合，まずは何かしらの形でサンプルの設定ファイル(ワークフロー)を目にすることになります．yamlで書かれたこの設定ファイルは，非常に読みやすくできているものの，最低限の機能しか使っていないので，他にどんなオプションがあるかが知りたくなるかと思います．
そんなときに読むのがWorkflow syntax for GitHub Actionsのページです．Workflow syntax for GitHub Actionsのページを開いてまずナルホドと思うのはその目次です．画像を見るとわかるように，レファレンスの目次はyamlのデータ構造と対応した表現で書かれています (例えば，"on.<event_name>.types"，設定がどこに書かれるのかイメージしやすいですよね)．
したがって，参考にしたいワークフローを見たときに知らない項目があったら，このレファレンスを開いて該当する構造の箇所を目次で探せば良いということです．もちろん検索しても良いわけですが，目次から探すと気になる項目に近みたときに目も目に入るので，理解を深めやすいと思います．
ワイルドカードの書き方を知りたくなったら...
また，このページの下部にはワイルドカードの書き方も乗っています (Workflow syntax for GitHub Actions#filter-pattern-cheat-sheet)．こちらは，ワークフローの実行条件を指定する際に使います．git ignoreみたいな記法なので，一度読めば大体覚えられると思います．
処理の中でGithub Actionsのメタ情報を使いたくなったら...
Github Actionsでワークフローを書いていると，「どのブランチ・コミットに対して処理を実行しているのか」「どのRunnerを使って処理しているのか」など，そういったユースケースが出てきます(処理を分岐したり，通知をslackに送りたいときなど)．
このようなGithub Actionsのメタ情報を扱う機能は，大きく3つ用意されています．
- 実行にかかわる情報にアクセスできる"Context"
- "Context"と一緒に使うことができる関数や演算子("Expression")
- 実際のコマンドを実行するシェルに自動で設定される"環境変数"
ContextとExpressionは共に${{ ~~~ }}というブラケットで囲って使用します．このブラケットに囲まれた箇所は，実行前に評価されて結果が埋め込まれます．いわばCのマクロ的な挙動になるのが特徴です．
Context
Contexts のページを見てみましょう．Contextには7種類あることが目次からわかります．Contextはそれぞれがオブジェクトとなっているので，Javascriptのオブジェクトのようにフィールドにアクセスできます(例えば"hoge.fuga[1]"のような記法)．
そして大事なのは一番下のContext Availabilityの項目です．Contextは場所によって使えたり使えなかったりします(例えば"step"に関するメタ情報が，実行のトリガーを決める"on"の配下にあったら変でしょう)．Context Availabilityには，どこでどのContextが使えるかの情報が書かれているのですが，一度目を通しておくことをお勧めします．意外な場所にもContextを使うことができ，想像以上にワークフローの要素を動的に変更できることがわかります．
Expression
Contextは単に値がオブジェクトとして置いてあるだけです．実行の有無を決める"if"の中で使う場合のために，限定的ながら演算子と関数が用意されています．Expressionsのページの目次を見ると，大きく5つの項目があることがわかります．
この中で使い方がわかりづらいのはfromJsonとtoJsonなので，少し補足します．
fromJson
大きく2つの使い方があり，
- Json文字列をオブジェクトに変換する
- 文字列を値(数値や真偽値)に変換する
この関数はContextにユーザーが値を追加した場合(これは漏れなく文字列になっているため)に使います(詳細は後述)．文字列をリテラルとして評価したい場合にも使えるというのはちょっと盲点なので注意です．また，前者の機能はyamlの一部として直接オブジェクトを埋め込みたい場合に使用可能です(詳細はサンプルを参照のこと)．
toJson
これは，Contextを実際の処理で使うために使用します．オブジェクトのままshellコマンドに埋め込むと空になってしまうので，一旦Json文字列に変換して，shellの中でパースし直して使う必要があるのです．
環境変数
読んで字の如くです．Github Actionsでは，yamlファイルの中でシェルコマンドを記述することができます．そのときにGithub Actions実行時に環境変数が自動で設定されているので，これを普通の環境変数として使うことができます．設定される環境変数はEnvironment variablesを参照してください．
Github Actionsのトリガーイベントから得られる情報を使いたくなったら...
実はContextの中で，トリガーとなるイベント(github.event)のデータ構造がどうなっているかは詳しい情報がありません．Github Appを作る際のwebhook情報を参照するようになっているのが原因です．
Webhook events and payloads のページに書かれているので，こちらを参考にしてください．
Github Actionsの実行結果画面をカスタマイズしたくなったら...
Github Actionsでは，シェルコマンドの中でホストに対して特別な命令を実行することができます("Workflow Command"という機能)．正直，労力を割くメリットは少ない気がしますが，Workflow commands for GitHub Actions から参照できます．
ステップやワークフローを跨いで値を使いたくなったら...
Workflow commands for GitHub Actions#setting-an-output-parameterの項目に書かれています．"Workflow Command"のほとんどは使いませんが，唯一タイトルにした使い道だけはマスターしたほうがいいです．これによってstepやjobを跨いで値を参照することが可能になるため，非常に柔軟なワークフローの構築が可能になります．
Githubから追加で情報を取りたいと思ったら...
おまけですが，ワークフローの実行結果一覧などが欲しくなるときもあると思います．そのような場合は，GitHub REST APIを参照することができます．
Discussion