🐱

ローカルで GitHub Actions が実行できる act のお作法を整理する

Jun Irie

2024/05/01に公開

はじめに

GitHub Actions (GHA) 、便利ですね。

便利なんですが、動作確認するのに PR 出してマージするのが煩わしい...。そもそも PR する前に動作確認しておきたいし、やたらに PR 作りたくもない...。

そんな悩みを解消してくれるのが act でした。これならローカルで動作確認できるので GHA 開発が捗ります！！

https://github.com/nektos/act

act 使ってみた記事は沢山ありますが、動かすまでに詰まったポイントをお作法として整理 してみました。act の使い方に悩まれている方の参考になれば幸いです。

2024/5/8 追記

act の実行に IAM ロールに追加設定が必要な点を追記しました。
AssumeRole するために sts:TagSession 権限を付与する

対象読者

GitHub Actions を使っている / 使おうとしている方
GitHub Actions の動作確認に困っている方
GitHub Actions で AWS の何かしらの操作をしている/したい方

act のインストール

User Guide - Installation に従ってインストールします。私の環境が Mac なので Homebrew でのインストール例を記載しておきます。

brew install act

基本のお作法

基本的には User Guide の抜粋です。

https://nektosact.com/usage/index.html

GITHUB_TOKEN は -s オプションで渡す

.secrets を使う方法もありますが、 -s オプションの方が楽です。

act -s GITHUB_TOKEN="$(gh auth token)"

Ruuner (ワークフローの実行環境) は Medium 以上を使う

Micro だと git コマンドすら入ってなくて困りました。なお、Medium でも less コマンドが入っていないなど困る場面が出てくる可能性はあります。

act -P ubuntu-latest=catthehacker/ubuntu:act-latest

Apple Silicon Mac の場合は `--container-architecture linux/amd64` を指定する

指定しなくても実行できますが、警告が出ます。

警告

WARN  ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠

明示的にアーキテクチャを指定することで警告が出なくなります。

act --container-architecture linux/amd64

AWS の操作を伴うお作法

act とは直接関係ないですが、Runner に less コマンドが入っていないことへの対策です。いくつか方法はありますが、以下の 2 つが簡単かと思います。

1. 環境変数 `AWS_PAGER=""` を設定する

AWS_PAGERを設定する場合

env:
  AWS_PAGER: ""
run: |
  aws sts get-caller-identity

2. `--no-cli-pager` オプションを指定する

--no-cli-pagerを指定する場合

run: |
  aws sts get-caller-identity --no-cli-pager

実際の GitHub Actions と同様に Actions 実行用の IAM ロールを作っておく

AWS の操作をする場合、恐らく aws-actions/configure-aws-credentials を利用すると思います。GitHub での実行と同様に role-to-assume で IAM ロールを指定する必要があります。実行内容に応じた IAM ロールをあらかじめ作成しておきます。

ロール ARN を inputs で受け取るようにしておけば汎用性が高まります。

sample_workflow.yml

name: Sample Workflow

on:
  workflow_call:
    inputs:
      aws_region:
        required: true
        type: string
      inputs:
        aws_role_arn:
          required: true
          type: string

jobs:
  sample_job:
    runs-on: ubuntu-latest
    steps:
      - name: checkout
        uses: actions/checkout@v4

      - name: configure aws credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-region: ${{ inputs.aws_region }}
          role-to-assume: ${{ inputs.aws_role_arn }}

  ...

実行するときは --input オプションで IAM ロール ARN を指定します。

act ... --input aws_role_arn=arn:aws:iam::xxxxxxxxxxxx:role/xxxx-sample-role

AWS アクセスキーは `.env` で指定する

Runner コンテナで実行するためか、ターミナルで環境変数を設定しても読み取ってくれませんでした。

.env

AWS_ACCESS_KEY_ID="********"
AWS_SECRET_ACCESS_KEY="********"
AWS_SESSION_TOKEN="********"

`AssumeRole` するために `sts:TagSession` 権限を付与する

OIDC を設定したうえで GitHub Actions を実行する場合は不要な設定です。act を実行する場合は IAM ユーザーや IAM Identity Center ユーザーの認証情報を使うことが想定されるため、IAM ロールの信頼関係の設定に追加の権限付与が必要です。

見慣れないアクションなので、知らないとハマりがちです。

AssumeRole する IAM ロールの「信頼関係」に以下のように設定を追加します。Principal は必要に応じて変更してください。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::xxxxxxxxxxxx:root"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"  # "sts:TagSession" を Action に追加する
      ],
    }
  ]
}

お作法を踏まえた実行例

以上を踏まえて、実行コマンドの例です。

act -P ubuntu-latest=catthehacker/ubuntu:act-latest --container-architecture linux/amd64 -s GITHUB_TOKEN="$(gh auth token)" -W .github/workflows/sample_workflow.yml --input aws_region=ap-northeast-1 --input aws_role_arn=arn:aws:iam::xxxxxxxxxxxx:role/xxxx-sample-role

謝辞

公式サイトをはじめ、Web 上の様々な情報に助けていただきました。この場を借りて御礼申し上げます。

SimpleForm Tech BlogPublication

リアルタイム法人調査システム「SimpleCheck」を開発・運営するシンプルフォーム株式会社の開発チームのメンバーが、日々の開発で得た知見や試してみた技術などについて発信していきます。 Publication 運用への移行前の記事は zenn.dev/simpleform からご覧ください。