DOCS/journey/troubleshooting/260309_gitea_git_credential_helper_표준화.md

3.7 KiB

tags
tags
infra
git
gitea
credential
auth
troubleshooting

260309 Gitea git credential helper 표준화

상위 원칙

관련 문서

배경

  • git.ro-being.com 대상 git push가 세션마다 인증 부족으로 반복 차단됐다.
  • 기존에는 로컬 흔적에서 인증 포함 URL을 찾아 일회성으로 푸시하는 방식에 의존했다.
  • 반복 작업을 줄이기 위해 로컬 전용 표준 helper 경로를 고정할 필요가 있었다.

Facts

  • 2026-03-09 작업 전 전역 Git 설정에는 github.com용 helper만 있었고 git.ro-being.com용 helper는 없었다.
  • 워크스페이스 로컬 흔적에서 유효한 Gitea 인증 포함 URL이 1건 확인됐다.
  • 아래 설정을 적용했다.
    • 전용 credential 파일: /home/admin/.config/git/gitea-credentials
    • 파일 권한: 600
    • 전역 helper: credential.https://git.ro-being.com.helper=store --file /home/admin/.config/git/gitea-credentials
    • Gitea 전용 옵션: credential.https://git.ro-being.com.useHttpPath=false
  • 검증 결과:
    • git ls-remote https://git.ro-being.com/ivada-infra/DOCS.git HEAD 성공
    • infra/DOCS의 새 커밋 c898949origin/main에 push 성공

Interpretation

  • 반복 실패의 본질은 Git 자체 문제가 아니라, Gitea용 표준 credential helper 부재였다.
  • GitHub는 gh auth git-credential helper가 있었지만, Gitea는 같은 수준의 비대화형 인증 경로가 없어서 세션마다 다시 막혔다.
  • 로컬 전용 credential store를 분리하면 토큰을 문서/응답/원격 URL에 노출하지 않고도 재현 가능한 push 경로를 유지할 수 있다.

조치 내역

  1. 로컬 전용 인증 흔적에서 현재 유효한 Gitea 자격 증명 확인
  2. /home/admin/.config/git/gitea-credentials 생성 및 600 권한 적용
  3. git.ro-being.com 전용 credential helper를 전역 Git 설정에 등록
  4. Gitea에 대해서는 credential.https://git.ro-being.com.useHttpPath=false로 호스트 단위 credential 매칭 정책 고정
  5. git ls-remote로 원격 읽기 검증
  6. infra/DOCS 커밋 c898949 push로 실제 쓰기 검증

검증

  • git config --global --get-all credential.https://git.ro-being.com.helper
    • store --file /home/admin/.config/git/gitea-credentials
  • git config --global --get credential.https://git.ro-being.com.useHttpPath
    • false
  • stat -c '%a' /home/admin/.config/git/gitea-credentials
    • 600
  • git ls-remote https://git.ro-being.com/ivada-infra/DOCS.git HEAD
    • c898949e52b2ab544cd3565cd9cdb630c06e0a15 HEAD
  • git -C /home/admin/infra/DOCS push origin main
    • ef666e6..c898949 main -> main

재발 방지

  • git.ro-being.com 작업 전 helper 유무를 먼저 확인한다.
  • 새 세션에서 Gitea push가 막히면, 원격 URL 변경보다 /home/admin/.config/git/gitea-credentials와 전역 helper 설정부터 확인한다.
  • 인증값은 로컬 전용 파일에만 두고, 문서/커밋/응답/스크립트 본문에 직접 남기지 않는다.

미확정 항목

  • 현재 credential의 발급 주체와 만료 정책은 이번 범위에서 재확인하지 않았다.
  • 향후 workspace-config 체계가 자리 잡으면 helper 파일 경로를 그 구조에 맞춰 재배치할지 검토가 필요하다.