---
tags: [infra, git, gitea, credential, auth, troubleshooting]
---

# 260309 Gitea git credential helper 표준화

## 상위 원칙
- [Writing Principles](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/writing-principles.md)
- [Global Principles](https://github.com/happybell80/0_VALUE/blob/main/00_Principles/global-principles.md)

## 관련 문서
- [infra/scripts 원격 미존재 푸시실패 및 조직레포 생성 조치](./260307_infra_scripts_원격_미존재_푸시실패_및_조직레포_생성_조치.md)
- [24서버 로빙 운영 자료 수집](../research/260309_24서버_로빙운영_자료수집.md)

## 배경
- `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`
  - 전역 옵션: `credential.useHttpPath=true`
- 검증 결과:
  - `git ls-remote https://git.ro-being.com/ivada-infra/DOCS.git HEAD` 성공
  - `infra/DOCS`의 새 커밋 `c898949`를 `origin/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. `credential.useHttpPath=true`로 저장소 경로 기준 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`
- `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 파일 경로를 그 구조에 맞춰 재배치할지 검토가 필요하다.