[운동 관리 앱 만들기] Levio - DAY 5: Mobile Codex 파이프라인 구축

기술적 의사결정

2026-05-22: GitHub Mobile 기반 Codex PR 파이프라인 채택

결정 내용: GitHub issue comment의 /codex <task> 명령을 GitHub Actions 트리거로 사용하고, openai/codex-action@v1이 브랜치 작업 후 테스트와 빌드를 통과하면 PR을 생성하도록 구성.

이유 / 배경: 사용자는 스마트폰에서 작업 지시를 내리고 GitHub Mobile에서 PR을 검토 및 merge하려는 흐름을 원함. GitHub Mobile은 PR 검토 경험이 안정적이고, GitHub Actions와 repository secret, PR API가 한 플랫폼 안에서 연결되어 자동화 구성이 단순함.

대안으로 고려했던 것: GitLab MR 중심 운영 (모바일 검토 경험이 약함), Slack/Telegram/webhook 봇 별도 구축 (추가 서버와 인증 관리 필요), main 직접 자동 merge (검토 단계가 사라져 위험함)

영향받는 문서 / 파일: .github/workflows/mobile-codex-pr.yml, docs/mobile-codex-pipeline.md, README.md, src/App.test.js

2026-05-22: GitHub를 기본 remote로 두고 GitLab을 보조 remote로 유지

결정 내용: origin fetch URL은 GitHub repo git@github.com:ginsengcandy/workout-tracker.git로 설정하고, origin push URL은 GitHub와 GitLab을 모두 등록. 기존 GitLab repo는 별도 gitlab remote로 보존.

이유 / 배경: GitHub Mobile, GitHub Actions, Netlify GitHub App을 중심으로 PR 검토와 배포를 단순화하면서도, GitLab 사용 경험과 백업 용도를 유지하고 싶었음. 한 번의 git push origin <branch>로 GitHub와 GitLab 모두에 브랜치가 반영되도록 구성하면 전환기 동안 두 호스팅을 병행할 수 있음.

대안으로 고려했던 것: GitLab만 canonical로 유지 (GitHub Mobile PR 흐름과 충돌), GitHub로 완전 이전 후 GitLab 삭제 (복구/백업 여지 감소), GitLab push mirror 설정 (UI 설정과 권한 관리가 추가로 필요)

영향받는 문서 / 파일: .git/config remote 설정, GitHub repo ginsengcandy/workout-tracker, GitLab repo kimsparadise0202/workout-tracker

2026-05-22: GitLab 최신 main을 기준으로 GitHub main 초기화

결정 내용: GitLab main이 로컬 main보다 앞서 있었으므로, 로컬 main을 gitlab/main으로 fast-forward한 뒤 GitHub main에 push.

이유 / 배경: GitLab main에는 feat/heatmap merge commit이 이미 존재했고, 로컬 main에는 GitLab에 없는 커밋이 없었음. 덮어쓰기 대신 fast-forward로 최신 canonical 상태를 GitHub에 복제하는 것이 안전했음.

대안으로 고려했던 것: GitHub 초기 main을 로컬 이전 상태로 유지 (GitLab 최신 merge 누락), GitLab main force push (원격 히스토리 손상 위험), 별도 merge commit 생성 (불필요한 히스토리 추가)

영향받는 문서 / 파일: 브랜치 main, remote tracking branch gitlab/main, GitHub main

2026-05-22: Netlify 배포 기준을 GitHub repo로 전환하기로 결정

결정 내용: Netlify site의 linked repository를 GitLab에서 GitHub ginsengcandy/workout-tracker로 바꾸는 방향으로 결정. production deploy는 GitHub main merge를 기준으로 실행되도록 운영.

이유 / 배경: 사용자는 GitHub Mobile에서 PR을 merge한 직후 결과가 Netlify에 반영되기를 원함. GitHub를 PR 검토와 merge의 중심으로 삼는다면 Netlify도 같은 GitHub repo를 바라봐야 merge 후 배포 경로가 직관적임.

대안으로 고려했던 것: Netlify는 GitLab을 계속 바라보고 GitHub merge 후 GitLab 동기화를 기다림 (동기화 실패 시 배포 누락 가능), GitHub와 GitLab 양쪽 deploy hook 유지 (운영 복잡도 증가)

영향받는 문서 / 파일: Netlify site settings, GitHub App repository access, docs/mobile-codex-pipeline.md

2026-05-22: main 자동 merge는 제외하고 PR 생성까지만 자동화

결정 내용: 모바일 Codex 파이프라인은 브랜치 생성, 코드 변경, 테스트, 빌드, push, PR 생성까지만 수행하고 main merge는 사용자가 GitHub Mobile에서 직접 수행.

이유 / 배경: 자동 코드 변경은 테스트를 통과해도 제품 의도나 UI 품질까지 완전히 보장하지 못함. 사용자가 모바일에서 최종 검토와 merge를 수행하면 속도와 통제 사이의 균형을 맞출 수 있음.

대안으로 고려했던 것: CI 통과 시 자동 merge (오작동 시 main 오염 가능), manual workflow_dispatch만 사용 (모바일 issue comment UX보다 번거로움)

영향받는 문서 / 파일: .github/workflows/mobile-codex-pr.yml, docs/mobile-codex-pipeline.md

2026-05-22: 기존 CRA 기본 테스트를 현재 앱 smoke test로 교체

결정 내용: learn react 링크를 찾던 기본 CRA 테스트를 현재 운동 기록 앱의 첫 화면 요소를 확인하는 smoke test로 변경.

이유 / 배경: 모바일 Codex PR 파이프라인은 PR 생성 전 npm test -- --watchAll=false를 실행함. 기존 테스트는 현재 앱 UI와 무관하여 항상 실패했기 때문에, 자동 PR 생성 경로를 막는 잘못된 게이트였음.

대안으로 고려했던 것: 테스트 단계 제거 (회귀 검증 약화), 실패하는 기본 테스트 방치 (자동 PR 생성 불가), 더 넓은 UI 테스트 작성 (이번 변경 범위를 넘어섬)

영향받는 문서 / 파일: src/App.test.js, .github/workflows/mobile-codex-pr.yml

2026-05-23: GitHub CLI를 PR 생성 도구로 채택

결정 내용: Homebrew로 GitHub CLI gh를 설치하고, 브라우저 device login으로 ginsengcandy 계정 인증 후 gh pr create로 PR을 생성.

이유 / 배경: GitHub CLI가 없으면 PR 생성에 Chrome UI 조작이나 수동 링크 클릭이 필요함. CLI를 설치하면 이후 PR 생성, PR 조회, Actions 확인 같은 반복 작업을 터미널에서 안정적으로 처리할 수 있음.

대안으로 고려했던 것: GitHub 웹 compare URL 수동 사용 (사용자 조작 필요), Chrome 자동화 (브라우저 권한과 세션 의존), GitHub API 직접 호출 (토큰 관리 필요)

영향받는 문서 / 파일: 로컬 Homebrew 설치 상태, GitHub CLI auth state, GitHub PR #1

2026-05-23: 모바일 Codex 파이프라인 변경분을 feature branch PR로 검토

결정 내용: 모바일 Codex workflow 변경분을 feat/heatmap 브랜치에 chore: add mobile Codex PR pipeline 커밋으로 저장하고, GitHub PR #1을 main <- feat/heatmap으로 생성.

이유 / 배경: 이미 feat/heatmap이 현재 작업 브랜치였고 GitHub/GitLab 양쪽에 push된 상태였음. main에 직접 반영하지 않고 PR로 검토하면 새 자동화 설정과 테스트 변경을 GitHub Mobile에서 확인한 뒤 merge할 수 있음.

대안으로 고려했던 것: main에 직접 push (검토 생략), 별도 브랜치로 cherry-pick (추가 브랜치 관리 필요), GitLab MR 생성 (GitHub Mobile 검토 목적과 맞지 않음)

영향받는 문서 / 파일: .github/workflows/mobile-codex-pr.yml, docs/mobile-codex-pipeline.md, README.md, src/App.test.js, GitHub PR https://github.com/ginsengcandy/workout-tracker/pull/1

2026-05-23: 기술적 결정 로그를 append-only 로컬 메모리로 운영

결정 내용: 모든 중요한 기술적 결정은 .local-notes/technical-decisions-2026-05-23.md에 append-only 방식으로 기록하고, 기존 기록은 변경하지 않음. 미래 Codex 세션이 이 규칙을 잊지 않도록 루트 AGENTS.md에 decision log 운영 지침을 추가.

이유 / 배경: 사용자는 기술적 의사결정을 나중에 다시 확인할 수 있는 지속적인 기록으로 남기고 싶어 함. 매번 명시적으로 요청하지 않아도 Codex가 결정사항을 기록하도록 하려면, git에서 제외된 실제 로그와 git으로 공유되는 작업 지침을 분리하는 방식이 가장 안정적임.

대안으로 고려했던 것: .local-notes에만 규칙을 기록 (미래 세션에서 발견하지 못할 수 있음), git으로 관리되는 docs/decisions.md에 기록 (사용자가 요청한 비관리 로컬 기록 방식과 다름), 기존 로그를 수정하며 정리 (append-only 요구와 충돌)

영향받는 문서 / 파일: AGENTS.md, .gitignore, .local-notes/technical-decisions-2026-05-23.md

(아래부터 고유 식별자로 관리하기 시작함)

TD-IDX-001 / 2026-05-23: 기존 기술적 결정 항목 식별자 매핑

결정 내용: 기존 append-only 기록은 원문을 수정하지 않고, 아래 인덱스로 안정 식별자를 부여함.

이유 / 배경: 사용자는 앞으로 기술적 결정과 트러블슈팅 문서를 상호 참조할 수 있도록 항목별 고유 식별자를 원함. 동시에 이전에 정한 append-only 원칙을 지키기 위해 기존 제목을 직접 고치지 않고 별도 매핑 항목으로 식별자를 부여함.

대안으로 고려했던 것: 기존 heading을 직접 수정 (append-only 원칙 약화), 앞으로의 항목에만 식별자 부여 (기존 결정과 상호 참조가 어려움)

영향받는 문서 / 파일: .local-notes/technical-decisions-2026-05-23.md, .local-notes/troubleshooting-log.md, AGENTS.md

관련 항목: TD-009

식별자 매핑:

• TD-001: 2026-05-22 / GitHub Mobile 기반 Codex PR 파이프라인 채택
• TD-002: 2026-05-22 / GitHub를 기본 remote로 두고 GitLab을 보조 remote로 유지
• TD-003: 2026-05-22 / GitLab 최신 main을 기준으로 GitHub main 초기화
• TD-004: 2026-05-22 / Netlify 배포 기준을 GitHub repo로 전환하기로 결정
• TD-005: 2026-05-22 / main 자동 merge는 제외하고 PR 생성까지만 자동화
• TD-006: 2026-05-22 / 기존 CRA 기본 테스트를 현재 앱 smoke test로 교체
• TD-007: 2026-05-23 / GitHub CLI를 PR 생성 도구로 채택
• TD-008: 2026-05-23 / 모바일 Codex 파이프라인 변경분을 feature branch PR로 검토
• TD-009: 2026-05-23 / 기술적 결정 로그를 append-only 로컬 메모리로 운영

TD-010 / 2026-05-23: 트러블슈팅 로그를 기술적 결정 로그와 분리

결정 내용: 기술적 의사결정은 .local-notes/technical-decisions-2026-05-23.md에 TD-###로 기록하고, 장애 조사와 해결 과정은 .local-notes/troubleshooting-log.md에 TR-###로 별도 기록. 두 문서는 관련 항목을 서로 참조함.

이유 / 배경: 의사결정 기록과 장애 해결 기록은 서로 연결되지만 목적이 다름. 의사결정 문서는 선택과 이유를 남기고, 트러블슈팅 문서는 증상, 조사, 원인, 해결, 재발 방지를 남겨야 나중에 빠르게 재사용할 수 있음.

대안으로 고려했던 것: 기술적 결정 로그 하나에 모두 기록 (문서가 비대해지고 장애 조사 흐름이 묻힘), Git tracked docs에 기록 (사용자가 요청한 로컬 비관리 메모리 방식과 다름), 트러블슈팅은 기록하지 않음 (같은 실패를 반복 조사할 위험)

영향받는 문서 / 파일: AGENTS.md, .local-notes/technical-decisions-2026-05-23.md, .local-notes/troubleshooting-log.md

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

TD-011 / 2026-05-23: CI 의존성 설치는 npm ci를 유지하고 lockfile을 npm 10 기준으로 보정

결정 내용: 모바일 Codex workflow의 dependency install 단계는 npm install로 완화하지 않고 npm ci를 유지. 대신 GitHub Actions Node 22 runner와 가까운 npm 10 계열로 package-lock.json을 재생성하여 누락된 optional peer lock entries를 보정.

이유 / 배경: npm ci는 lockfile 불일치를 조기에 잡아주는 CI용 설치 방식이므로 자동 PR 파이프라인의 재현성을 높임. 실패 원인이 workflow 자체가 아니라 lockfile의 npm 10 관점 누락 항목이었으므로, 설치 명령을 느슨하게 바꾸는 것보다 lockfile을 정확히 만드는 것이 더 안전함.

대안으로 고려했던 것: workflow에서 npm install 사용 (CI 재현성 약화), Node/npm 버전을 로컬 npm 11에 맞춤 (GitHub Actions 표준 LTS 환경에서 멀어짐), dependency install 검증 제거 (자동 PR 품질 게이트 약화)

영향받는 문서 / 파일: package-lock.json, .github/workflows/mobile-codex-pr.yml, .local-notes/troubleshooting-log.md

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

TD-012 / 2026-05-23: GitHub Actions의 PR 생성 repo 권한을 활성화

결정 내용: GitHub repository Actions workflow permission에서 default_workflow_permissions=write와 can_approve_pull_request_reviews=true를 활성화하여 GITHUB_TOKEN이 pull request를 생성할 수 있게 함.

이유 / 배경: 모바일 Codex 파이프라인은 gh pr create로 자동 PR을 생성해야 함. Workflow-level pull-requests: write만으로는 충분하지 않고, repository-level 설정에서 Actions의 PR 생성/승인 권한이 꺼져 있으면 GitHub GraphQL API가 createPullRequest를 거부함.

대안으로 고려했던 것: Codex 작업 브랜치는 자동 push하고 PR은 사용자가 수동 생성 (모바일 자동화 완성도 저하), 별도 PAT secret으로 PR 생성 (토큰 관리 부담 증가), workflow에서 PR 생성 단계를 제거 (파이프라인 목표와 충돌)

영향받는 문서 / 파일: GitHub repo Actions settings, .github/workflows/mobile-codex-pr.yml, GitHub PR https://github.com/ginsengcandy/workout-tracker/pull/4

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