[운동 관리 앱 만들기] Levio - DAY 5: 트러블슈팅

TR-001 / 2026-05-23: Mobile Codex workflow failed during dependency installation

증상: GitHub Mobile에서 issue comment로 /codex 명령을 실행했지만 Mobile Codex PR workflow가 Install dependencies 단계에서 실패. 실패한 run은 26296953177이고, 단계는 npm ci.

원인: package-lock.json에 optional peer dependency lock entries가 일부 빠져 있어 GitHub Actions runner의 npm 10 계열 npm ci가 lockfile을 불완전하다고 판단. 로그에는 Missing: picomatch@4.0.4 from lock file, Missing: yaml@2.9.0 from lock file이 표시됨. npx npm@10 install --package-lock-only 실행 결과 node_modules/@netlify/build/node_modules/picomatch와 node_modules/tailwindcss/node_modules/yaml 항목이 추가되며 원인과 일치함.

조사 과정: gh run list로 실패한 workflow run을 찾고 gh run view --log-failed로 실패 로그를 확인. 로컬 현재 npm 11에서는 npm ci --dry-run이 통과했지만, runner와 가까운 npm 10으로 npx npm@10 ci --dry-run을 실행해 lockfile 수정 후 통과 여부를 확인.

해결: npx npm@10 install --package-lock-only로 package-lock.json을 재생성하여 누락된 optional peer lock entries를 추가. 이후 npx npm@10 ci --dry-run이 통과함.

재발 방지: GitHub Actions에서 사용하는 Node/npm 계열과 맞는 npm으로 lockfile을 갱신한다. CI dependency 단계는 npm install로 완화하지 않고 npm ci를 유지하여 lockfile 불일치를 조기에 감지한다.

관련 항목: TD-010, TD-011

TR-002 / 2026-05-23: Mobile Codex workflow failed while reading Codex server info

증상: GitHub Mobile에서 /codex 명령을 다시 실행했지만 Mobile Codex PR workflow가 Run Codex 단계에서 실패. 최신 실패 run은 26298819897. 로그의 핵심 에러는 Error: Failed to read server info from /home/runner/.codex/26298819897.json.

원인: openai/codex-action@v1이 Codex Responses API proxy의 server info JSON 파일을 읽으려 했지만, 해당 파일이 생성되지 않음. 로그의 with: 출력에 openai-api-key 입력이 보이지 않고, openai/codex-action은 OpenAI API key를 GitHub Actions secret으로 제공해야 하므로 OPENAI_API_KEY secret이 없거나 비어 있을 가능성이 가장 높음. 이 경우 action이 더 명확한 missing API key 오류 대신 server info JSON 누락 오류로 실패할 수 있음.

조사 과정: gh run list --workflow "Mobile Codex PR"로 최근 실패 run을 확인하고, gh run view 26298819897 --log-failed로 실패 단계와 로그를 확인. Install dependencies 단계는 지나갔고, 실패가 Run Codex 내부의 read-server-info 명령에서 발생함을 확인. 이전 run 26298363344도 같은 Failed to read server info 패턴으로 실패했음.

해결: 아직 미적용. GitHub repository settings에서 Actions secret OPENAI_API_KEY가 존재하고 값이 비어 있지 않은지 확인해야 함. secret을 추가/수정한 뒤 같은 이슈에 새 /codex ... 댓글을 작성해 workflow를 재실행한다.

재발 방지: workflow 시작부에 OPENAI_API_KEY secret 존재 여부를 명시적으로 검사하는 preflight step을 추가하면, Codex action 내부 ENOENT 오류 대신 사람이 이해하기 쉬운 실패 메시지를 남길 수 있음.

관련 항목: TD-001, TD-010, TR-001

TR-003 / 2026-05-23: Mobile Codex workflow failed while creating a pull request

증상: Mobile Codex PR workflow가 코드 수정, 테스트, 빌드, 브랜치 push까지 완료했지만 Open pull request 단계에서 실패. 실패 메시지는 pull request create failed: GraphQL: GitHub Actions is not permitted to create or approve pull requests (createPullRequest).

원인: Workflow file에는 pull-requests: write 권한이 있었지만, GitHub repository-level Actions 설정의 can_approve_pull_request_reviews 값이 false였음. 이 값이 false이면 GitHub UI의 "Allow GitHub Actions to create and approve pull requests"가 꺼진 상태이며, GITHUB_TOKEN의 GraphQL createPullRequest 호출이 차단됨.

조사 과정: gh api repos/ginsengcandy/workout-tracker/actions/permissions/workflow로 repo Actions workflow permissions를 확인. 응답은 {"default_workflow_permissions":"write","can_approve_pull_request_reviews":false}였고, 실패 로그의 GraphQL 권한 오류와 일치함. 최신 실패 run 26299615315 로그에서 이미 push된 브랜치가 codex/mobile-allow-the-save-of-temporary-workout-data-and-mak-06f5091임을 확인.

해결: GitHub API로 repository workflow permission을 default_workflow_permissions=write, can_approve_pull_request_reviews=true로 변경. 이미 push된 모바일 Codex 작업 브랜치로 PR https://github.com/ginsengcandy/workout-tracker/pull/4를 수동 생성.

재발 방지: 모바일 Codex 파이프라인을 운영하려면 repo Settings > Actions > General > Workflow permissions에서 Read and write permissions와 Allow GitHub Actions to create and approve pull requests를 모두 켜야 함. 신규 repo로 이전하거나 repo 설정을 재구성할 때 체크리스트에 포함한다.

관련 항목: TD-001, TD-012, TR-001, TR-002