GitHub Actions との距離を縮めるツールたち - ESM アジャイル事業部開発者ブログ

試行錯誤しながら何かを作っているとき、ひとつひとつの作業に対するフィードバックに時間がかかるとなかなか捗らないことがあります。特にCI/CDの設定では、リモートのサーバ上で何が起きているのかを把握するのに手間や時間がかかったりして思うようにいかないことがあったりするのではないかと思います。今回は、GitHub Actions の設定をするうえで、手元のマシンでやれることの幅を広げる便利なツールを紹介します。

Act

act を使うことで、手元のマシン上で GitHub Actions のYAMLファイルを読み込んで実行できます。act コマンドを叩くと .github/workflows 以下のYAMLファイルが読み込まれ、定義されている job が Docker コンテナ上で実行されます。act の提供する環境は GitHub Actions と100%互換性があるわけではないのでいくらか注意が必要ですが、すぐに結果が返ってくるので、記述方法を調べつつトライアンドエラーを繰り返す際に役立ちます。またデバッグ用途だけでなく、ローカル用の Makefile を用意する代わりに act を叩くといった task runner 的な使い方もできます。act の素晴らしさについて詳しくはリポジトリの README を確認していただくとして、ここでは act を使ううえで私がつまずいた箇所を中心にいくつかの注意点を紹介します。

ソースコードのチェックアウトに PAT が必要

GitHub Actions で定義する job としては、最初のステップとして actions/checkout でリポジトリからコードを clone してくるというのがよくあるパターンだと思いますが、 actions/checkout は GitHub の personal access token (PAT) に依存しているので、act から使う場合は自分で渡してあげる必要があります。act はデフォルトで .secrets ファイルを secrets として読み込みますので、手軽な方法としてはそのファイルに token を記述しておくことができます。

GITHUB_TOKEN=...

GitHub Actions との違いについて

act がデフォルトで使う Docker イメージには、GitHub Actions の用意する環境で提供されているものが含まれていなかったりします。例えば sudo や Docker が無くて act のときだけ失敗する、といったことが起こりえます。そのため、両方の環境に対応させるためにちょっとした変更が必要な場合があります。act の実行時には ACT という環境変数が設定されるので、それを元に環境ごとに動作を変える、ということが可能です。多用すると見通しが悪くなりそうなので悩ましいですが。

if [ -n "$ACT" ]; then
  # https://docs.docker.com/engine/install/debian/
  # https://docs.docker.com/compose/install/
  curl -fsSL https://get.docker.com | sh -
  curl -L "https://github.com/docker/compose/releases/download/1.28.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
  chmod +x /usr/local/bin/docker-compose
fi

docker-compose build...

別の手段として、より互換性の高い Docker image を使うという手段もあるようです。

User Namespace Remapping を有効にした Docker Daemon について

セキュリティ上の理由やコンテナ上で作られたファイルのパーミッション問題のために user namespace remapping を有効にして　Docker を起動している場合、act を走らせるには --userns=host を渡す必要があります。act は　host network mode でコンテナを起動する都合上、 user namespace remapping を利用できません (詳細)。remapping を有効にしたまま act を実行しようとすると、次のような Docker のエラーメッセージが表示されてしまいます。

Error: Error response from daemon: cannot share the host's network namespace when user namespaces are enabled

remapping は、コンテナ作成時に --userns=host を渡すことで一時的に無効にできます。act からも同じオプションを渡せるようにパッチを投げました。取り込まれましたが、まだリリースされていないので、現時点 (2021/03/02) では master のコードをビルドして使う必要があります。

action-tmate

ここでもうひとつ別のツールを紹介します。act は便利な一方、完全な互換性は期待できないので、GitHub の runner 上で直接確認しなければならない場合もあるでしょう。Circle CI や Travis CI みたいに、一時的に SSH でつなげられると便利ですよね。 mxschmitt/action-tmate は Tmate を使って GitHub Actions の実行環境に SSH 接続する手段を提供します。手元には ssh があれば大丈夫。調査したい箇所の前後でこの action を呼ぶことで、Tmate のセッションが開始されます。

- name: Setup tmate session
  uses: mxschmitt/action-tmate@v3
  if: ${{ always() }}

GitHub Actions ではあるステップが失敗すると、後続のステップはデフォルトでスキップされるので、if: ${{ always() }} をつけておくとよいでしょう。また、この action はデフォルトで sudo を使うので、 sudo のないコンテナ上で呼び出す場合は、sudo: false をオプションとして渡す必要があります。

ちなみに act がデフォルトで提供する環境では、action-tmate が依存しているパッケージが足りなかったりで簡単には動かせそうにありませんでした。とはいえ、act の場合は手元から触れるコンテナ上で実行されるため、目的のコンテナ上でシェルを立ち上げれば済む話で、わざわざ ssh で接続する必要はなさそうです。

おわりに

GitHub Actions の実行環境をより身近にし、開発を助けるツールについて紹介しました。よりよい開発環境づくりのお役に立てれば幸いです。