When Codex Cannot Connect to GitHub, Authentication May Not Be the Problem

GitHub would not connect. Was my account the problem?

Late in September, while setting up a development environment with Codex, I ran into an unexpected problem.

I wanted to connect a project to GitHub to manage its source code, but GitHub was not reachable from Codex.

My first assumption was an authentication problem. Perhaps the SSH key was wrong, the credentials registered with GitHub were invalid, or Codex needed a separate sign-in.

But investigating the failure revealed something else.

There was more than one problem.

Codex's network access was restricted, and Git was not using the SSH configuration I expected. Only after separating those issues could I establish a working connection.

First clue: even the GitHub hostname would not resolve

I started by checking whether the GitHub server could be resolved.

getent hosts github.com

This command asks the system's name-resolution mechanism for information about a hostname.

In the Codex execution environment at the time, it returned no result. Initially that looked like a DNS configuration problem.

But a failed hostname lookup does not prove that a DNS server is broken. Access to the network may be blocked, or a policy governing the execution environment may prevent name resolution.

With a tool like Codex that runs commands inside a sandbox, it is important to distinguish the permissions of a normal Ubuntu terminal from those of the Codex execution environment.

Instead of immediately changing my GitHub credentials, I began examining Codex's network policy.

First cause: networking was restricted by the Codex sandbox

Codex was using a workspace-write sandbox.

That mode generally permits changes within a workspace while restricting access elsewhere. But permission to write project files and permission to connect to an external network are separate capabilities.

In my environment, the Codex sandbox had network access disabled. The relevant configuration I eventually applied was:

~/.codex/config.toml

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

After restarting the Codex Remote session, hostname lookup worked as expected.

An important caveat belongs here:

Allowing network access changes the execution environment's permission boundary; it is not merely a cosmetic error fix.

This is not a universal default that every developer should enable. The decision should depend on whether the task genuinely needs external connectivity, how much the code can be trusted, and any network policies imposed by the organization or system.

In my case, GitHub connectivity was necessary for managing the source code, so I enabled the required access. But this fixed only the first problem.

Second cause: Git was not using the intended SSH configuration

Even after network access was restored, GitHub operations did not immediately work. The next step was to investigate SSH.

If a GitHub remote uses SSH, having internet access is not sufficient. It also matters which SSH executable Git runs, which configuration file that executable reads, and which key it selects.

A typical initial check is:

ssh -T git@github.com

This tests SSH authentication with GitHub. When the SSH server's fingerprint needs verification, compare it with GitHub's official documentation before trusting the connection.

In my environment, specifying the SSH configuration file explicitly helped isolate the issue:

GIT_SSH_COMMAND="ssh -F $HOME/.ssh/config" \
  git push --dry-run

The important piece is GIT_SSH_COMMAND, an environment variable that tells Git which SSH command to use.

With the -F option, I could explicitly choose the SSH configuration file and see whether Git used the settings I intended. git push --dry-run checks what a push would do without actually transferring a new commit to the remote.

After confirming that this approach worked, I configured Git's SSH command:

git config --global core.sshCommand \
  "ssh -F $HOME/.ssh/config"

This is an example from my environment, not a command to paste into every setup without checking first.

A --global Git configuration affects other repositories used by the same account. With multiple GitHub identities or different SSH keys, setting the command only in the relevant repository may be safer. Avoid overwriting an existing global value before understanding what it does.

Why did these need to be treated as separate problems?

Both failures looked like an inability to connect to GitHub. But each belonged to a different part of the process.

Step	What it asks	How to check
Name resolution	Can the system resolve the hostname?	`getent hosts github.com`
Execution policy	May the Codex sandbox use the network?	Inspect Codex configuration and execution context
SSH authentication	Will GitHub accept this SSH identity?	`ssh -T git@github.com`
Git configuration	Is Git using the intended SSH settings?	Compare with `GIT_SSH_COMMAND`
Repository access	Can the current repository connect to its remote?	`git push --dry-run`

Changing SSH keys repeatedly before fixing the network restriction would not have solved the first failure. Likewise, restoring networking could not automatically repair an incorrect SSH configuration.

Network connectivity and user authentication are separate steps.

An order of checks for similar failures

1. Do not change GitHub credentials first

Determine whether the problem is connectivity or SSH authentication. If an existing SSH key previously worked, avoid automatically generating a replacement key or overwriting it.

2. Compare a regular terminal with the Codex environment

If an operation succeeds in the WSL2 Ubuntu terminal but fails when Codex runs it, examine the sandbox and approval policy. Running on the same PC does not mean both processes have the same permissions.

3. Once networking works, inspect SSH settings

Check SSH connectivity and the Git remote URL. When multiple keys exist, it is especially important to identify the active SSH configuration and selected identity.

4. Verify before pushing

After changing configuration, inspect the current repository and branch, and test connectivity where possible before pushing important changes. A successful authentication fix is not the same as a successful production deployment.

What this experience taught me

When this issue first appeared, I saw it only as a GitHub authentication error. In reality, I had to address the Codex sandbox's network restriction and Git's SSH configuration separately.

Since then, I have tried not to focus solely on the first likely cause suggested by an error message. It can be quicker to ask which steps work correctly and where the first failure actually occurs.

AI coding tools can make writing code easier, but they do not eliminate the need to understand the network, filesystem permissions, and authentication model of the environment in which they run.

What looks like an authentication error may be a networking issue; even after networking is fixed, authentication still needs to be tested on its own.

It seems like a small distinction, but learning it firsthand made a real difference.

Official references

Written with AI assistance based on a real development incident and its resolution. These settings describe the environment at that time and are not universal fixes.