Skip to content

Why gh CLI won’t run in Codex and how to handle it

Key Points

  • Codex runs with strict filesystem/network/permission sandboxing.
  • gh depends on network access, auth tokens, and installation. If any is missing, it fails.
  • Prefer Actions + github-script or direct REST calls via curl. If you must run gh, ensure network escalation and proper tokens.

Common symptoms

  • gh: command not found (CLI not installed)
  • authentication failed / HTTP 401/403 (missing token or insufficient scopes)
  • Logs mention blocked network or need for escalation

Root causes

1) Not installed: Codex images may not ship with gh and global installs can be restricted.

2) Network restrictions: Outbound calls require “escalated permissions” (an approval step) in Codex.

3) Missing/insufficient tokens: GH_TOKEN (or GITHUB_TOKEN) must be present with the right scopes; forked runs don’t receive secrets.

A. Decide where to run the action

  • If possible, move write-operations to GitHub Actions using actions/github-script (no gh needed).

B. Replace gh with REST in Codex

  • Use curl with Authorization: Bearer $GH_TOKEN.
  • Request network escalation only when needed, avoid storing tokens on disk.

C. Offload to GitHub Actions

  • Trigger workflows or handle issues/PRs in Actions where GITHUB_TOKEN is available and permissions are explicit.

D. If you must use gh, checklist

  1. Is gh installed? (Often not.)
  2. Do you have network escalation approved?
  3. Is GH_TOKEN present with sufficient scopes?
  4. Is this a fork/external event (secrets not provided)?

Examples (REST)

Create 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 test","body":"REST path without gh"}'

Dispatch a workflow:

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"}'

Best practices

  • Security first: short‑lived, least‑privilege tokens via env vars.
  • Reduce gh dependencies; design for CI reuse.
  • Clear error messages for “not installed / blocked network / insufficient permission”.

Design your automation so Codex focuses on edits and PR authoring, while GitHub Actions performs networked side effects using GITHUB_TOKEN and explicit permissions.