コンテンツにスキップ

Codexでghコマンドが実行できない理由と対処

この記事のポイント

  • Codex（この環境）は安全のため「ファイルシステム」「ネットワーク」「権限」をサンドボックス制御しています。
  • gh は「ネットワーク通信」「認証トークン」「インストール有無」に依存するため、そのどれかが満たされないと失敗します。
  • 回避策は「承認付きで実行（ネットワーク権限）」「GH_TOKEN/GITHUB_TOKEN を設定」「未インストールなら gh を使わず REST API/curl へ置換」などです。

症状の典型例

  • gh: command not found（CLI 未インストール）
  • authentication failed / HTTP 401/403（トークン未設定 or 権限不足）
  • 「ネットワークが使えないため失敗」や、Codex の実行ログで「エスカレーションが必要」

原因の整理

1) ツール未インストール

  • Codex ランタイムに gh がプリインストールされていない場合があります。
  • この環境では任意のグローバルインストールが制限されることがあり、gh の導入自体が不可なケースがあります。

2) ネットワーク制限（承認フロー）

  • Codex はデフォルトでネットワークが制限されています。重要な外部通信（gh による API 呼び出し等）は「承認付き実行（escalated permissions）」が必要です。

3) 認証トークンの不足/不適切

  • gh は GH_TOKEN などのトークン設定が必要です。権限スコープ（repo, workflow など）が不足していると 403 になります。
  • フォークからの実行や外部イベントでは、セキュリティ仕様上、シークレットが渡らないため失敗します。

推奨の回避策・代替手段

A. まずは要件を見極める

  • その処理は「ローカル（Codex）」で必要ですか？ それとも「GitHub Actions 上」で実施すべきですか？
  • 可能なら、GitHub Actions の actions/github-script や REST API（curl）に寄せると、ローカルで gh を使う必要がなくなります。

B. Codex 内で gh 相当を行う方法

  • gh の代わりに REST API を直接叩く（curl -H "Authorization: Bearer $GH_TOKEN" ...）。
  • 必要に応じて Codex の「承認付き実行」を使いネットワークを許可する（この手順はオペレーション時に明示的承認が求められます）。
  • トークンは最小権限・最小期間で。複製/漏洩防止のためファイル保存は避け、環境変数で一時供給。

C. GitHub Actions にオフロードする

  • レポジトリにワークフローを用意し、必要な操作は Actions 内で実行（GITHUB_TOKEN 利用、権限は permissions: で最小化）。
  • 例：Issue 作成は actions/github-script で十分。gh を呼ぶ必要はありません。

D. gh を使いたい場合のチェックリスト

  1. gh がインストールされているか（多くの Codex 環境では未インストール想定）
  2. ネットワーク承認（エスカレーション）が取れているか
  3. GH_TOKEN（または GITHUB_TOKEN）が適切な権限で設定されているか
  4. フォーク / 外部イベント起点ではないか（シークレットが渡らないケース）

具体例（REST API 置換）

Issue 作成（例）:

curl -sS -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GH_TOKEN" \
  https://api.github.com/repos/<owner>/<repo>/issues \
  -d '{"title":"Codex検証用","body":"gh不使用のRESTパス"}'

ワークフローの再実行（例）:

curl -sS -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GH_TOKEN" \
  https://api.github.com/repos/<owner>/<repo>/actions/workflows/<file>.yml/dispatches \
  -d '{"ref":"main"}'

ベストプラクティス

  • セキュリティ第一：トークンは環境変数で一時的に注入、最小権限で運用。
  • 再利用性：ローカルの gh 依存を避け、CI に寄せる設計（github-script など）。
  • 可観測性：失敗時ログに「権限不足」「ネットワーク拒否」「未インストール」のどれかを明示。

よくある質問（FAQ）

  • Q. Codex で gh をインストールできますか？
  • A. 環境によっては不可です。可能でもネットワーク承認や実行制限で運用コストが高くなるため、REST/Actions 代替を推奨します。
  • Q. GITHUB_TOKEN と GH_TOKEN の違いは？
  • A. GITHUB_TOKEN は Actions 内で自動供給されるトークン、GH_TOKEN は gh/API 用に自分で用意する個人アクセストークン（PAT）です。用途と権限が異なります。

このドキュメントは Codex CLI（安全なサンドボックス環境）での実務的な運用を前提にまとめています。設計段階で「どこで何を実行するか」を切り分けることで、gh 依存を極小化し、安定した自動化パイプラインを構築できます。

関連ガイド