[GitHub]Actionsで上手く行かない時や選択肢に迷う時にチェックしておきたいポイント

GitHub Actionsを使う際に、思った通りになかなか行かない時や選択に迷った時等、困った時の指針としていることを書き出してみました。
2020.11.24

はじめに

なかなか上手くいかず、ぐったりする時には音楽を聞いて気を紛らわせています。

8月11日辺りからはTo the Edgeになりました。

そんなぐったりする原因のGitHub Actionsの挙動について、動作を調べる上で事前に理解おきたいハマりな箇所を備忘録込めて書き出してみました。

GitHub ActionsでのAPI呼び出し

Actions上でAPIを呼び出す際には、以下の3通りの手段が検討できます。

  • REST API直接呼び出し
  • octokit/request-actionによる呼び出し
  • MarketPlaces上のActions

いずれも結局はAPIを叩いている状態に変わりないのですが、API自体のアップデートが早く、追従する必要のあるoctokitやActionsの対応が遅れることもあります。機能面で充実している時や枯れていない場合にはREST APIを直接呼ぶほうが確実かもしれない、ということです。

REST API

最新のドキュメントはdocs.github.com/v3/に存在します。developer.github.comは古くなっている可能性があるため注意しましょう。

ドキュメント内サンプルを見ながら、実際にcurlを使って呼び出してみるスタイルになると思われます。ただ、POST/PUTリクエストはやや面倒なためAdvanced REST clientを使うとよいでしょう。

なお、REST APIを直接呼び出す場合には幾つか注意点があります。

ステータスコード404が所謂not foundではない

Typically, we send a 404 error when your client isn't properly authenticated. You might expect to see a 403 Forbidden in these cases. However, since we don't want to provide any information about private repositories, the API returns a 404 error instead.

常日頃触っていて「ふざけんな」って思っている部分です。パラメータミスによる認証エラーなのか、URLが本当に存在しないのか更に検証が必要になります。

とはいえ、URLの存在有無確認自体はシンプルです。確認したいAPIより上のパスでGETリクエストを送り、レスポンスにURLが含まれるかどうかを確認します。

上記のようにレスポンスにURLが含まれている場合は、パラメータミスによる認証エラーの可能性が高くなります。

HeaderにUserAgentを忘れない

Actionsを使っていると忘れがちです。特に指定はないので、後から見た時にわかりやすい名前にしておきましょう。

octokit/request-actionによる呼び出し

octokit/requestを内部で利用しています。要はActions上でoctokitを実行したい時に使えます。

事前指定されていないフィールドが含まれると警告がでる

以下のような警告が出る場合は、action.yml内で定義されていないフィールドが含まれています。実行そのものは可能ですが、エラーとなった場合は原因切り分けが結構手間です。

Warning: Unexpected input(s) 'repository', 'required_status_checks', 'enforce_admins', 'required_pull_request_reviews', 'restrictions', valid inputs are ['route', 'mediaType']

MarketPlaces上のActions

Actionを探すときにはここを見ることが多いかと思われます。

REST APIで対処できない操作に関するActionは恐らく存在しない

MarketPlace上にあるActionを探していると、ないものとあるものがくっきりとしていることに気がつくかもしれません。基本的にREST APIで操作できない類のものについてはActionにも存在しません。例えば、ブランチの削除等。

MarketPlaceに登録されているActionの多くは確認している限り、REST API等を通してGitHub上のリポジトリを直接操作するものです。公式のドキュメントでAPIを経由させることに触れている点をもって相違ないと思います 。

You can create actions by writing custom code that interacts with your repository in any way you'd like, including integrating with GitHub's APIs and any publicly available third-party API.

もし、Workflowの仮想環境にチェックアウトしたリポジトリ内で操作を確定したとして、それをリモート側に反映する場合に先にリモートが更新されていると衝突して止まる可能性があることを踏まえてものだと考えられます。

やってみたい操作があってもActionが見当たらないときは、REST APIに該当するものはないかを確認してみるとよいでしょう。

あとがき

REST APIが返すエラーは独特すぎて検証にも手間がかかりやすいです。ではActionだと楽になるかといえば、REST APIのレスポンスを上手く扱えていない場合には直接REST APIを触るよりも更に厄介な可能性もあります。

Advanced REST clientがなかったら足止めをくらいつづけていたであろうというケースもありつつ、REST APIを触った上でのトラブルに関する知見は案外転がっていないので、体当たりし続けるしかないと思っています。

Actionsを使う上で困ったときの参考になれば幸いです。

参考リンク