Why `gh` doesn’t work in Codex and practical workarounds (with verify steps)¶

Summary¶

Codex restricts filesystem/network/permissions for safety.
gh requires installation, network, and tokens; missing any of these causes failures.
Use direct REST calls in Codex and offload side‑effects to GitHub Actions. This page includes verify steps that work here.

Typical failures¶

gh: command not found (not preinstalled)
HTTP 401/403 (missing or insufficient token scopes)
Blocked network unless you approve escalation

Architecture to avoid breakage¶

1) Keep Codex focused on edits and light verification; network only when needed (with approval) 2) Offload writes (issues/labels/dispatch) to Actions using GITHUB_TOKEN + explicit permissions:

Practical recipes (REST in Codex)¶

Prereqs: Approve network when prompted. Provide GH_TOKEN via env var with least privileges.

Read repo info (unauthenticated GET)¶

curl -sS https://api.github.com/repos/<owner>/<repo> | head -n 5

Dispatch a workflow (POST; requires `GH_TOKEN`)¶

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

Operational guidance: - Do not store tokens on disk; inject via env - Minimal scopes only - Use Codex’s approval flow for outbound calls for auditability

Offload to Actions¶

Use actions/github-script or official actions for issues/PRs. Manage secrets/permissions in workflows; keep Codex for content changes.

Verify in this environment¶

Connectivity: run the GET above and observe JSON output (approve network if asked)
Optional write: export GH_TOKEN=... (repo scope) and run the dispatch call for your workflow/branch

Design for safety and reliability: Codex proposes diffs; Actions performs networked side‑effects with GITHUB_TOKEN.

Why gh doesn’t work in Codex and practical workarounds (with verify steps)¶