Skip to content

Troubleshooting

Jump to bottom
ClarusIubar edited this page May 3, 2026 · 4 revisions

트러블슈팅

배포가 안 보일 때

GitHub Actions에 보이는 workflow 이름과 Cloudflare 실제 배포 시간은 다를 수 있습니다.

확인 순서:

  1. GitHub Actions의 deploy-pages, deploy-worker, smoke, protected-smoke 실행 여부 확인
  2. Cloudflare Pages/Worker 최근 배포 시간 확인
  3. 문서-only 변경인지 코드 변경인지 확인
  4. [skip ci]가 포함된 커밋인지 확인

문서-only 변경인데 배포가 돌 때

워크플로우 조건을 확인합니다.

  • docs/wiki-only 변경인지
  • path filter가 있는지
  • [skip ci]가 반영되는지
  • Pages 배포와 Worker 배포가 분리되어 있는지

GitHub 로그인 UI가 뜰 때

자동화 작업에서는 브라우저 로그인이나 계정 선택 UI를 열지 않습니다.

권장 경로:

  • gh auth token
  • Git Credential Manager token
  • GitHub REST API

Markdown이 깨질 때

PowerShell에서 백틱은 escape 문자입니다.

증상:

  • `refactor`가 \refactor처럼 깨짐
  • 줄바꿈이 literal \n으로 들어감

대응:

  • single-quoted here-string 사용
  • REST patch 후 \refactor, literal \n 존재 여부 확인

UTF-8이 깨질 때

확인할 것:

  • 문서가 UTF-8로 저장됐는지
  • PowerShell 출력 인코딩이 UTF-8인지
  • 한글 본문을 잘못된 인코딩으로 재저장하지 않았는지
  • wiki clone과 repo clone의 문서가 섞이지 않았는지

관련 문서

CodeQL/Security/Quality 경고

처리 순서:

  1. finding이 현재 코드 기준인지 확인합니다.
  2. stale finding인지 확인합니다.
  3. 정확한 파일/라인을 확인합니다.
  4. 같은 유형의 경고가 더 있는지 검색합니다.
  5. 수정 후 lint/typecheck/test를 실행합니다.
  6. PR 또는 이슈에 해결 근거를 남깁니다.

반복 발생했던 유형:

  • unused import
  • unreachable code
  • identical operands
  • vulnerable dependency
  • unsafe tmpdir handling

GitHub Wiki safe.directory 경고

Windows sandbox 사용자와 실제 파일 소유자가 다르면 아래 경고가 나올 수 있습니다.

detected dubious ownership in repository

전역 설정을 남발하지 말고, 가능하면 명령마다 아래처럼 제한합니다.

git -c safe.directory=D:/JamIssue/.tmp-wiki -C .tmp-wiki status

Wiki 링크가 클릭되지 않을 때

원인:

  • 문서명을 백틱으로 감쌈
  • repo 파일명과 wiki slug를 혼동
  • .md 확장자를 링크에 직접 넣음

해결:

  • [표시명](Development-Guide)처럼 실제 존재하는 Wiki 페이지 slug 사용
  • 내부 링크 검사 실행

문서 내용이 줄었을 때

정리 작업에서 요약형으로 바꾸면 정보가 사라질 수 있습니다.

복구 기준:

  • 이전 commit과 diff stat 비교
  • 삭제량이 큰 문서 우선 점검
  • 링크/한글 정리는 유지하되 상세 표와 체크리스트를 복원
  • 보강 후 line count와 내부 링크 검사 실행

PR/merge 확인이 막힐 때

GitHub UI 대신 REST/GCM token 경로를 사용합니다.

확인할 것:

  • branch pushed 여부
  • PR 생성 여부
  • check-runs 상태
  • merge commit SHA
  • main 최신 SHA

빠른 진단 표

증상 먼저 볼 것
로그인 실패 OAuth redirect URI, Worker env, session secret
지도 깨짐 bootstrap 응답, Naver script, z-index
알림 안 옴 notification row, SSE, REST fallback
배포 안 보임 skip ci, Cloudflare dashboard, Actions
문서 깨짐 UTF-8, PowerShell encoding, Markdown escaping

Clone this wiki locally