ローカルで検証する「act」ハンズオン

actは、GitHub ActionsのワークフローをローカルのDockerコンテナー上でそのまま実行するCLIツールです。pushする前に「このワークフローは本当に動くか」を手元で検証できます。

・pushしなくても検証できる: ワークフローYAMLの構文ミスやステップの実行結果をローカルで確認できる
・.actrc で環境差異を吸収: actのデフォルトrunnerイメージは軽量すぎて動かないActionがあるため、-P オプションでラベルごとにイメージをマッピングして解決する
・軽量な確認手段もある: act -l はDockerなしでジョブ構成だけ確認できる
・実プロジェクトで体験できる: 本記事では実際に手元で動かしている act_sample（TODOアプリ）のCI設定を題材にする

この記事では、act のセットアップから実行、つまずきやすいポイントまでを実際に手を動かしながらひととおり体験します。

Transcript

1. ローカルで検証する「act」 ハンズオン 2026-09-05 北海道もくもく会 オンライン vol.15 発表資料 1
2. 自己紹介 ひだお 好きなこと: 情報整理：Markdown-vault × AI 自作ツール開発：PWA / UserScript / ... 活動: 技術記事投稿：Qiita / Zenn / dev.to OSS個人開発：VS Code / Chrome拡張 / PWA モットー: 最適・最小・理性的 / 三方利益 HN: 2
3. TL;DR を使うと、GitHub ActionsのワークフローをpushせずローカルのDockerコンテナー で検証できる → .actrc の -P オプションでrunnerイメージを act-latest / full-latest にマッピン グする act -l はDocker起動不要でジョブ構成を確認できる 題材アプリはテスト/lint/認知的複雑度/依存監査の4ジョブ並列構成 act 3
4. 対象読者 のワークフローを書いたことがある Docker Desktop（またはPodman）の基本操作ができる 「pushしないとCIの結果が分からない」フィードバックの遅さに困っている GitHub Actions 4
5. なぜactか は便利だが、ワークフローの記述ミスや依存関係のズレは 「pushしてWeb UIで赤くなってはじめて気づく」ことが多く、フィードバックループが長 くなりがち。 GitHub Actions しなくても検証できる: 構文ミスやステップの実行結果をローカルで確認 .actrc で環境差異を吸収: 軽量runnerイメージで動かないActionの問題を解決 軽量な確認手段もある: act -l はDockerなしでジョブ構成だけ確認できる 実プロジェクトで体験できる: 実際に動かしているTODOアプリのCI設定を題材にする push 5
6. きっかけ を組んだ直後、実際に手を動かしていて次の場面に何度も遭遇した。 CI ワークフローのYAMLを少し書き換えるたびに、確認のためだけにpushして結果を待つ 必要があった lint / 認知的複雑度 / 依存監査のどれか1つだけ素早く再確認したい場面が多く、pushベ ースでは効率が悪かった 「架空のサンプルではなく、実際に運用しているワークフローをそのまま検証できる」 ハンズオンが作れると思い立った 6
7. Step 1: 題材プロジェクト① 題材はbun + Hono + React + bun:sqliteで組んだ最小構成のTODOアプリ act_sample 。 createTodoRepository （DB層）と createApp （Honoルーティング層）を分離したテスト容 易な構成。 act_sample/ ├── .actrc # actのrunnerイメージ設定 ├── .github/workflows/ci.yml # GitHub Actionsワークフロー ├── biome.json # Lint/Format/認知的複雑度の設定 ├── bunfig.toml # bun test のプリロード設定 └── src/ ├── client/ (App.tsx, api.ts, main.tsx) ├── server/ (app.ts, db.ts, index.tsx) └── test/ (happydom.ts) 7
8. Step 1: 題材プロジェクト② は つの独立したジョブで構成される。 ジョブID 内容 test tsc --noEmit 型チェック + bun test CI 4 lint biome check . complexity 認知的複雑度チェック（ジョブ名は Cognitive complexity check ） audit bun audit いずれも checkout → setup-bun → cache → bun install --frozen-lockfile が共通の 前段。 （本検証環境で bun test を実行し、3ファイル26テストすべて成功確認済み） 8
9. Step 2: act をインストールする 前提条件: actはDockerコンテナー上でジョ ブを実行するため、 Docker Desktop（またはPodman）が起動 している必要がある。 # Windows（今回の検証環境） winget install nektos.act # macOS brew install act $ act --version act version 0.2.89 9
10. Step 3: .actrc でrunnerイメージをマッピング のデフォルトrunnerは軽量な -slim イメ ージ。 setup-bun のような一部Actionが動かないこ とがあるため、 本プロジェクトの4ジョブが使う ubuntuslim を、より多くのツールを含む 中間サイズの act-latest イメージに差し替 える。 -P < >=< > で runs-on の参照先を 置き換える。 act ラベル -P ubuntu-latest=catthehacker/ubuntu:full-latest -P ubuntu-slim=catthehacker/ubuntu:act-latest イメージ 10
11. Step 4: test ワークフローを確認する① ジョブが最初に定義されている。 jobs: test: name: bun test steps: - uses: actions/checkout@v7 - uses: oven-sh/setup-bun@v2 - run: bun install --frozen-lockfile - name: Type check run: bunx tsc --noEmit - name: Run tests run: bun test env: ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }} 11
12. Step 4: ワークフローを確認する② ジョブは secrets.ACCESS_TOKEN を参照している。 actはデフォルトで secrets を空文字として扱うため、 --secret-file でローカル用secretファイルを渡さないと bun test が認証失敗で落ちる。 test リポジトリ直下に（ .gitignore 済みの） .secrets を用意し、 ACCESS_TOKEN=<値> の形式で記述（値は sample:sample のBase64） 実行方法はStep 6で解説 12
13. Step 4: ワークフローを確認する③ 残り3ジョブは、それぞれ1コマン ドを実行するだけのシンプルな構 成。 noExcessiveCognitiveComplexity の閾値は biome.json 側で 15 に設 定。 lint: steps: - run: bunx biome check . complexity: steps: - run: bunx biome lint --only=complexity/noExcessiveCognitiveComplexity . audit: steps: - run: bun audit 13
14. Step 5: ジョブ一覧を表示する はワークフローをパースするだ けなので、Docker起動不要で実行でき る。 （↑ 本ハンズオンの検証環境で実際に出 力された結果。4ジョブとも Stage 0 ＝ 並列実行） act -l $ act -l Stage Job ID Job name Events 0 test bun test pull_request,push 0 lint Biome lint & format check push,pull_request 0 complexity Cognitive complexity check push,pull_request 0 audit bun audit push,pull_request 14
15. Step 6: ワークフローを実行する # pushイベントの全ジョブ（testがsecretsを参照するため--secret-fileが必要） act push --secret-file .secrets # 特定ジョブのみ act push -j test --secret-file .secrets act push -j lint act push -j complexity act push -j audit 15
16. スクリーンショット で act push --secret-file .secrets を実行し、4ジョブすべて Job succeeded まで確認。 Podman Desktop 16
17. 技術スタック選定基準 ワークフローファイルをそのまま実行でき、CI専用の別DSLを覚える必要がない .actrc による act-latest / full-latest 指定: GitHub-hosted runnerに近い構成で、 -slim で頻発する「ツール不足で落ちる」問題を避けやすい 4ジョブ並列構成: 分割しているため act push -j <job> でピンポイントに再実行できる act: いずれも「pushせずに素早く確認できるか」を基準に選定。 17
18. ハマりポイント① Cannot connect to the Docker daemon が起動していないことが原因。 起動してから再実行する。 Docker Desktop 18
19. ハマりポイント② setup-bun -slim 等のsetup系Actionが失敗する イメージにはツールが不足している場合がある。 → .actrc で act-latest や full-latest イメージにマッピングする（本記事の方法） 19
20. ハマりポイント③ 初回実行がとても遅い イメージ（いずれも数GB）の初回pullに時間がかかる。 2回目以降はローカルキャッシュが効くため高速化する。 act-latest / full-latest 20
21. ハマりポイント④ Apple Silicon (M1/M2) で exec format error 等 イメージのアーキテクチャ不一致が原因のことがある。 → --container-architecture linux/amd64 の指定を検討する 21
22. ハマりポイント⑤ secrets act を参照するステップで失敗する はデフォルトで secrets を空として扱う。 → act push --secret-file .secrets 等でローカル用secretファイルを渡す 22
23. ハマりポイント⑥ ジョブは通るがGitHub上の実行と結果が微妙に違う act → のDockerイメージはGitHub-hosted runnerの完全な再現ではない。 あくまで「ロジックの事前検証」用途と割り切るのが実践的 23
24. まとめ を使えば、GitHub Actionsのワークフローをpush前にローカルで検証できる .actrc の -P オプションでrunnerイメージを差し替え、setup系Actionの動作不足を防 ぐ まずは act -l でジョブ構成を確認し、慣れたら act push -j <job> で部分実行する テスト・lint・複雑度チェック・依存監査のように独立したジョブに分割しておくと、 actでの部分実行がしやすくなる act ジョブ数が増え needs による依存関係が複雑化してきた場合は、 act -l の Stage 列で実行順序を確認しながら運用するとよい。 24
25. ご清聴ありがとうございました 25