GitHub 연결이 안 되는데, 계정 문제일까?
Codex로 개발 환경을 구성하던 9월 말, 예상하지 못한 문제가 생겼습니다.
프로젝트를 GitHub와 연결해 소스코드를 관리하려고 했는데, Codex에서 GitHub에 정상적으로 접근하지 못했습니다.
처음에는 GitHub 인증 문제라고 생각했습니다. SSH 키가 잘못됐거나, GitHub 계정에 등록한 인증정보에 문제가 있거나, Codex에서 별도의 로그인이 필요한 상황이라고 생각하기 쉬웠습니다.
하지만 점검을 진행하면서 의외의 사실을 발견했습니다.
당시 문제는 하나가 아니었습니다.
Codex의 네트워크 접근이 제한된 문제와 Git이 SSH 설정을 제대로 사용하지 못한 문제가 따로 있었던 것입니다. 이 두 가지를 구분하고 나서야 정상적으로 연결할 수 있었습니다.
첫 번째 단서: GitHub 주소부터 조회되지 않았다
먼저 GitHub 서버에 접근할 수 있는지 확인했습니다.
getent hosts github.com일반적으로 이 명령은 시스템의 이름 조회 기능을 통해 해당 호스트의 주소 정보를 확인할 때 사용합니다.
그런데 당시 Codex 실행 환경에서는 조회 결과가 나오지 않았습니다. 처음에는 DNS 설정이 잘못된 것처럼 보였습니다.
하지만 도메인 조회 실패라는 현상만으로 실제 DNS 서버가 고장 났다고 결론 내릴 수는 없습니다. 네트워크 자체가 차단돼 있거나, 실행 환경의 정책 때문에 이름 조회가 실패할 수도 있기 때문입니다.
특히 Codex처럼 샌드박스 안에서 명령을 실행하는 도구라면 일반 Ubuntu 터미널의 접근 권한과 Codex의 접근 권한을 구분해서 확인해야 합니다.
이때부터 GitHub 인증정보를 수정하기보다 Codex가 실행되는 환경의 네트워크 정책을 확인하기 시작했습니다.
첫 번째 원인: Codex 샌드박스의 네트워크 제한
당시 Codex는 workspace-write 샌드박스를 사용하고 있었습니다.
이 모드는 주로 작업 공간의 파일을 수정하도록 허용하면서 그 밖의 접근을 제한하는 방식입니다. 그런데 작업 공간에 파일을 쓸 수 있다는 것과 외부 네트워크에 연결할 수 있다는 것은 서로 다른 권한입니다.
당시에는 Codex의 샌드박스에서 네트워크 접근이 차단된 상태였습니다. 실제로 적용했던 설정의 핵심은 다음과 같습니다.
~/.codex/config.toml
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = true이후 Codex Remote 세션을 다시 시작하고 도메인 조회를 확인했을 때 정상적으로 동작했습니다.
여기서 주의할 점이 있습니다.
네트워크 접근 허용은 단순한 오류 수정이 아니라 실행 환경의 권한 범위를 변경하는 작업입니다.
해당 설정은 모든 개발 환경에서 무조건 사용해야 하는 기본값이 아닙니다. 외부 네트워크 접근이 실제로 필요한지 확인하고, 실행할 코드와 프로젝트의 신뢰 수준을 고려해야 합니다. 조직이나 개발 환경에서 더 제한된 네트워크 정책을 운영한다면 그 정책을 따르는 것이 우선입니다.
제 경우에는 GitHub에 연결해 소스코드를 관리해야 했기 때문에, 필요한 네트워크 접근을 허용하는 방향으로 설정했습니다.
하지만 여기서 문제가 모두 끝나지는 않았습니다.
두 번째 원인: Git이 사용해야 할 SSH 설정이 달랐다
네트워크 연결을 복구한 뒤에도 GitHub 작업이 곧바로 정상화되지는 않았습니다. 이번에는 SSH 설정을 확인해야 했습니다.
Git에서 GitHub 저장소에 접근할 때 SSH 방식을 사용한다면, 단순히 인터넷에 연결된 것만으로는 충분하지 않습니다. Git이 어떤 SSH 프로그램을 실행하고, 어떤 설정 파일을 읽고, 어떤 인증 키를 사용할지도 중요합니다.
일반적으로 다음 명령으로 연결 상태를 점검할 수 있습니다.
ssh -T git@github.com이 명령은 GitHub와의 SSH 인증을 점검하는 용도입니다. 최초 연결 시 서버 지문 확인이 필요하다면 GitHub 공식 문서와 대조해야 합니다.
제 환경에서는 Git 작업에 사용할 SSH 설정 파일을 명시하는 방법으로 문제를 확인했습니다.
GIT_SSH_COMMAND="ssh -F $HOME/.ssh/config" \
git push --dry-run여기서 중요한 것은 GIT_SSH_COMMAND입니다. 이 환경 변수는 해당 Git 명령을 실행할 때 사용할 SSH 명령을 지정합니다.
-F 옵션으로 읽을 SSH 설정 파일을 명시하면, Git이 원하는 설정을 사용해 연결되는지 확인할 수 있습니다. git push --dry-run은 실제 변경사항을 push하지 않고 전송 절차를 점검할 때 사용할 수 있습니다.
당시에는 이 방법으로 연결을 검증했고, 정상 동작하는 것을 확인한 후 Git의 SSH 명령 설정에도 반영했습니다.
git config --global core.sshCommand \
"ssh -F $HOME/.ssh/config"단, 이 명령은 예시로 그대로 실행하기보다 자신의 환경에 맞게 검토해야 합니다.
--global은 해당 사용자 계정의 다른 Git 저장소에도 영향을 줄 수 있습니다. 여러 GitHub 계정이나 서로 다른 SSH 키를 사용한다면 특정 저장소에만 설정하는 방식이 더 적합할 수 있습니다. 기존 설정을 확인하지 않은 채 전역 설정을 덮어쓰는 것은 피해야 합니다.
왜 두 문제를 구분해야 했을까?
이번 문제를 해결하면서 가장 중요하다고 느낀 부분입니다. GitHub에 연결되지 않는다는 증상은 같았지만 실제로 확인해야 할 대상은 달랐습니다.
| 확인 단계 | 확인하는 문제 | 점검 방법 |
|---|---|---|
| 이름 조회 | 도메인 주소를 조회할 수 있는가? | getent hosts github.com |
| 실행 환경 | Codex 샌드박스의 네트워크 접근이 허용됐는가? | Codex 설정과 실행 환경 확인 |
| SSH 인증 | GitHub가 SSH 인증을 받아들이는가? | ssh -T git@github.com |
| Git 설정 | Git이 의도한 SSH 설정을 사용하는가? | GIT_SSH_COMMAND로 비교 |
| Git 작업 | 해당 저장소에 접근할 수 있는가? | git push --dry-run |
첫 번째 문제가 해결되지 않은 상태에서 SSH 키만 계속 변경한다면 원인을 찾기 어려웠을 것입니다. 반대로 네트워크 연결을 복구했다고 해서 SSH 인증 문제까지 자동으로 해결되는 것도 아닙니다.
네트워크 연결과 사용자 인증은 서로 다른 단계이기 때문입니다.
같은 문제를 만난다면 이렇게 확인해 보세요
1. GitHub 인증정보부터 바꾸지 않기
현재 오류가 네트워크 문제인지, SSH 인증 문제인지 먼저 구분합니다. 특히 기존 SSH 키가 정상적으로 사용되고 있었다면 새로운 키를 무조건 생성하거나 기존 키를 덮어쓰지 않는 편이 안전합니다.
2. 일반 터미널과 Codex 실행 환경을 구분하기
WSL2 Ubuntu 터미널에서는 정상인데 Codex가 실행한 명령에서만 실패한다면, 샌드박스나 승인 정책을 확인할 필요가 있습니다. 같은 컴퓨터에서 실행된다는 이유만으로 두 환경의 접근 권한이 같다고 생각해서는 안 됩니다.
3. 네트워크가 정상이라면 SSH 설정 확인하기
SSH 연결과 Git 원격 저장소 설정을 확인합니다. 특히 여러 SSH 키를 사용하는 환경에서는 어떤 설정 파일과 인증 키가 선택되는지 점검하는 것이 중요합니다.
4. 실제 push 전에 검증하기
설정을 변경한 뒤에는 곧바로 중요한 변경사항을 push하기보다 현재 저장소와 브랜치를 확인하고, 가능한 범위에서 연결을 먼저 검증합니다. 설정 수정이 성공했다고 해서 운영 배포까지 성공했다는 의미는 아닙니다.
이번 경험에서 배운 점
이번 문제를 처음 만났을 때는 GitHub 인증 오류라고만 생각했습니다. 하지만 실제로는 Codex 샌드박스의 네트워크 제한과 Git의 SSH 설정 문제를 각각 해결해야 했습니다.
이 경험 이후로는 오류 메시지가 나타났을 때 가장 먼저 떠오르는 원인 하나에 매달리지 않으려고 합니다. 어느 단계까지 정상이고, 어디부터 실패하는지 확인하면서 문제를 나누어 보는 것이 더 빠른 해결 방법일 수 있기 때문입니다.
특히 AI 개발 도구를 사용하면 코드 작성은 쉬워지지만, 도구가 실행되는 환경의 네트워크·파일 접근 권한·인증 방식까지 자동으로 이해되는 것은 아닙니다.
인증 오류처럼 보이는 문제가 실제로는 네트워크 문제일 수 있고, 네트워크를 해결한 뒤에도 인증 설정은 별도로 확인해야 합니다.
작은 차이처럼 보이지만, 이번에 직접 겪으며 배운 중요한 점이었습니다.
함께 읽으면 좋은 글
공식 참고 자료
실제 개발 과정에서 겪은 문제와 해결 경험을 바탕으로 AI의 작성 보조를 받아 정리했습니다. 예시 설정은 당시 환경에 적용한 방법이며, 모든 개발 환경에 동일하게 적용되는 해결책은 아닙니다.