actがOrbStackにつながらないときの確認手順 — MacのローカルCIと本番の境界

actとOrbStackでローカルCIを動かしたいのに、Dockerのコマンドは通ってactだけ接続できない。そんなときは、まず両者が見ているDockerの接続先を比べる。act公式は、現在選択中のDocker contextをそのまま利用しない点を明記している。

ただし、接続できればGitHub Actionsを完全再現できるわけではない。ローカルでテストコマンドを早く確認することと、GitHub上の権限・レビュー・デプロイを確認することは分けて考える必要がある。

この記事は2026年10月7日に公式資料を照合した設定・切り分けガイド。編集環境にはactとDocker CLIがなく、以下のCI実行例を実機で完走したという検証報告ではない。導入済みのMacで確認する順序と、結果の読み方を示す。

最初に「接続できない」の範囲を分ける

自分なら、いきなりsocketのパスを書き換える前に次の順番で状況を記録する。

確認	見るもの	次に調べる場所
command -v docker	CLIが見つかるか	見つからなければCLI導入・PATH
docker context show	選択中のcontext名	意図したOrbStack接続か
docker info	Docker Engineへ到達するか	OrbStackの起動状態・接続先
command -v act	actが見つかるか	act導入・PATH
対象を絞ったact実行	最初に失敗する箇所	接続・イメージ・stepのどこか

たとえば、docker info自体が失敗しているなら、ワークフローのYAMLを書き直しても接続は直らない。一方、コンテナ作成後のnpm ciで止まるなら、Docker Engineへの接続から調べ直すより、そのstepのログを見る方が早い。

「actが動かない」という一言でまとめず、最後に成功した段階を残しておくと、別の人に相談するときにも状況が伝わりやすい。

Docker contextから接続先を確認する

OrbStackはDocker Engineを提供する。Docker自体の使い方は公式のコンテナ説明で確認できる。

docs.orbstack.dev

OrbStack公式: Docker containers OrbStackのDocker EngineとCLIの説明。

まず、選択中のcontextとその接続先を読み取る。

docker context show
docker context inspect --format '{{.Endpoints.docker.Host}}'

表示された接続先が意図したOrbStackのものか確認する。別のDocker Engineやリモート接続を選んでいる場合、そのまま次へ進まない。端末に複数のDocker環境があるなら、名前だけで決めず接続先も確認しておく。

act公式が示す対処は、その接続先をDOCKER_HOSTで渡す方法だ。次は接続先取得に成功した場合だけactを実行する、対象ワークフローを限定した例。

ACT_DOCKER_HOST="$(docker context inspect --format '{{.Endpoints.docker.Host}}')" &&
DOCKER_HOST="$ACT_DOCKER_HOST" act push \
  -W .github/workflows/ci.yml \
  -j test

ci.ymlとtestは自分のワークフローファイル・job IDへ置き換える。接続先の指定をこの1回に限定できるので、動作確認のためにシェル全体の設定を変更する必要はない。

nektosact.com

act公式: Docker contextの制約 選択中contextとDOCKER_HOSTの関係を確認。

nektosact.com

act公式: Custom container engine Docker Engine API互換エンジンへの接続方法。

ここで大事なのは、存在しそうなsocketパスを推測して固定しないこと。別のマシンのパスをコピーしても、今の端末で使っている接続先と一致するとは限らない。

最初はテストjobだけで確認する

actは対象ワークフローやjobを指定できる。最初の確認では、公開・通知・リリースを含む全ワークフローをまとめて動かすより、内容を確認したテストjobに絞る。ただし依存jobがあれば、それらの処理内容も確認が必要だ。

次の例は、Node.jsプロジェクトにtestスクリプトとロックファイルがあることを前提にした、小さなワークフロー案だ。既存プロジェクトへそのまま追加する前に、使っているNode.jsのバージョンとテストコマンドを合わせる。

name: Test
on: push
jobs:
  test:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npm test

ローカルでどこまで確認したかは、次のように段階を分けて記録する。

接続: Docker Engineへ到達した / 未確認
準備: runner imageを取得した / 取得で失敗
実行: npm ciまで成功 / npm testで失敗
判定: テスト成功 / 失敗 / 最後まで未実行
GitHub側: CI未実行 / 実行URLと結果

「コンテナが起動した」と「テストが通った」を別にしておけば、途中終了を成功と取り違えにくい。失敗ログにはコマンドと最初のエラー行を添え、認証情報を含む環境変数の一覧は貼らない。

nektosact.com

act公式: Usage guide ワークフロー・job選択と設定ファイルの書式。

ランナーの違いで失敗している場合

actの標準イメージは、GitHub提供ランナーの全ツールを備えているわけではない。公式資料では、コンテナと仮想マシンの差も説明されている。ubuntu-22.04というラベルだけを見て同じ環境だと判断しない。

イメージを指定する場合の例は次のとおり。

DOCKER_HOST="$ACT_DOCKER_HOST" act push \
  -W .github/workflows/ci.yml \
  -j test \
  -P ubuntu-22.04=catthehacker/ubuntu:act-22.04

この例は、前節で接続先を取得済みであることが前提。イメージの取得時間やディスク使用量は環境ごとに変わるため、初回から速度改善を約束することはできない。

Apple Siliconなら、GitHub側とローカル側のCPUアーキテクチャも確認したい。ネイティブ依存を含むプロジェクトでは、OS名だけでなく実行環境の差が原因になり得る。エラーを見ずに全プロジェクトへ同じオプションを固定するより、必要なアーキテクチャとイメージの対応を確かめて選ぶ。

また、Mac上で動かしているからといってLinuxコンテナがmacos-latestの代わりになるわけではない。actにはホスト上で直接動かす選択肢もあるが、その場合もGitHubのmacOSイメージと自分のMacの同一性は保証されない。

nektosact.com

act公式: Runners runner imageとホスト実行の範囲・制限。

ローカル成功後もGitHub側へ残す検証

公式の未対応一覧には、concurrency、jobの権限設定、実行時間制限、Environment関連などの制約が載っている。OIDCを前提としたデプロイも、ローカルテストの成功だけで正しく設定できたとは判断できない。

nektosact.com

act公式: Unsupported functionality 本番と同じだと扱ってはいけない機能を確認。

自分なら、結果を次のように分ける。

確認したいこと	ローカルでの目的	最終的な確認場所
単体テストの失敗	修正と再実行を素早く回す	GitHub側でも同じcommitを確認
環境依存のビルド失敗	ログを見て原因候補を絞る	対象runnerのCI
デプロイの承認待ち	ローカル成功を根拠にしない	GitHub Environment等の実設定
同時実行の抑制	ローカルで再現できたと決めない	GitHub上の実行履歴
認証・権限	テストに必要な範囲を分ける	承認された本番検証手順

actを導入する価値は、すべてをローカルへ移すことではなく、失敗原因を調べる一往復を短くできるかにある。まず一つのjobで、直したい失敗を確認できるかを見る。そこで効果がなければ、GitHubの実行ログを中心に調べる方が適切な場合もある。

Docker環境そのものの切り分けはDockerのパフォーマンス調査、アプリとDBをまとめた開発環境はDocker ComposeとClaude Codeのワークフローも参照してほしい。