# Gitea authenticated access 운영 지침 이 문서는 Gitea Agent harness가 Gitea의 authoritative state를 읽고 승인된 mutation을 수행할 때 사용하는 canonical access 계약이다. 모든 agent와 skill은 특정 transport를 정본으로 취급하지 않고, 이 문서의 identity·credential·readback 조건을 충족하는 authenticated API adapter를 사용한다. ## 고정 origin과 transport - 허용된 Gitea origin은 exact `https://gitea.jsfamily.quest`다. - Authenticated API adapter는 전용 Gitea MCP connection 또는 release/spec/impl 등 현재 role의 credential을 사용하는 직접 Gitea REST client일 수 있다. - MCP method 이름, REST client 구현과 command 성공은 정본이 아니다. 위 origin이 반환한 authenticated response와 fresh readback이 정본이다. - 다른 origin, mirror API, public web page, unauthenticated response 또는 다른 role의 adapter로 fallback하지 않는다. - Redirect는 자동 추적하지 않는다. 특히 credential을 다른 origin에 전달하지 않는다. ## Identity gate 1. 모든 workflow는 첫 authoritative read 전에 authenticated adapter로 현재 사용자를 읽는다. REST adapter는 exact `GET /api/v1/user`를 사용한다. 2. Stable numeric account ID, login과 현재 workflow role을 기록한다. Transport에 따라 login 표시가 달라도 stable account ID가 같으면 같은 identity다. 3. 예상 role identity를 확인할 수 없거나 API가 `401`, `403`, redirect, malformed response 또는 anonymous identity를 반환하면 fail-closed한다. 4. Workflow 동안 adapter와 credential source를 바꾸지 않는다. 재인증이 필요하면 현재 operation을 중단하고 snapshot부터 다시 시작한다. ## 직접 REST adapter - Base URL은 exact `https://gitea.jsfamily.quest/api/v1`로 고정하고 TLS certificate 검증을 끄지 않는다. - Token은 현재 role profile의 exact `$HERMES_HOME/.env`에 `GITEA_TOKEN`으로 저장하고 해당 파일의 mode를 `0600`으로 유지한다. Named profile에서는 `$HERMES_HOME`이 `~/.hermes/profiles/`이므로 같은 변수 이름을 사용해도 role별 token이 격리된다. 승인된 external secret manager를 사용하면 같은 profile scope에 `GITEA_TOKEN`으로 주입한다. 다른 profile, inherited ambient token, interactive prompt 또는 public access로 fallback하지 않는다. - Token을 URL, command argv, Git config, remote URL, log, exception text, state, artifact 또는 repository file에 기록하지 않는다. - Client는 token을 process 내부에서 읽어 `Authorization` header에 넣거나 보호된 file descriptor·stdin과 동등한 mechanism으로 전달한다. Secret이 shell expansion 후 argv에 나타나는 호출은 금지한다. - Response status와 JSON shape를 검증한다. Collection endpoint는 Gitea pagination metadata에 따라 마지막 page까지 읽고 cardinality를 기록한다. - `429`와 일시 오류는 read operation에서만 bounded retry할 수 있다. Mutation timeout·오류는 blind retry하지 않고 authoritative reconciliation을 먼저 수행한다. ## Repository와 Git - Repository metadata, default branch와 branch full SHA는 authenticated adapter로 exact target에서 읽는다. - Git clone/fetch/push credential은 API token을 credential-bearing URL에 넣지 않고 short-lived askpass 또는 동등한 child-process mechanism으로 전달한다. - Git command 성공만으로 remote state를 확정하지 않는다. Fetch 후 default-branch ref를 API SHA와 비교하고, push 후 exact remote ref를 authenticated adapter로 다시 읽는다. ## Mutation과 readback - Direct REST와 MCP에 동일한 승인 gate, exact payload, idempotency, drift 검사와 readback 규칙을 적용한다. - Mutation 직전에 target identity, approval snapshot과 baseline을 다시 읽는다. - 승인된 exact endpoint와 payload만 한 번 호출한다. Unstated default field에 의존하지 않는다. - 성공 response만으로 완료를 주장하지 않는다. Exact target을 fresh readback하고 author stable account ID, payload, timestamp, commit/ref와 collection cardinality를 baseline과 비교한다. - Timeout, malformed response 또는 connection loss 뒤에는 같은 mutation을 재호출하기 전에 complete collection을 한 번 읽어 결과를 reconciliation한다. 결과가 없거나 여러 개이거나 경쟁 mutation과 구분할 수 없으면 uncertain/partial로 중단한다. ## Credential 안전 - Credential 값은 role profile의 secret store에만 저장하고 repository, harness 문서와 workflow artifact에는 저장하지 않는다. - Child process에 credential이 필요하면 최소 범위 environment 또는 보호된 descriptor로 전달하고 종료 시 helper와 temporary file을 제거한다. - Credential의 존재 여부, source와 cleanup 결과만 보고하며 값을 출력하지 않는다. - Read-only 단계에는 필요한 최소 scope를, tag push·review·Issue mutation에는 승인된 작업에 필요한 scope만 사용한다. ## Fail-closed 조건 다음 중 하나라도 발생하면 authenticated operation을 완료로 보고하지 않는다. - 허용 origin 또는 target repository 불일치 - Authenticated stable account identity 확인 실패 - Role credential source 불명확 또는 다른 role credential 사용 - Redirect, TLS 검증 실패, `401`, `403` 또는 malformed API response - Pagination 미완료 또는 baseline cardinality 불명확 - Mutation 결과와 fresh readback 불일치 - Credential 노출 또는 helper cleanup 결과 불확실 ## 보고 완료 보고에는 adapter 종류 자체보다 다음 검증 결과를 포함한다. - exact Gitea origin - authenticated stable account ID와 login - exact repository와 authoritative default branch full SHA - 사용한 transport 종류와 role credential source의 이름만 표시한 provenance - 수행한 mutation의 exact target과 fresh readback 결과 - pagination, drift, reconciliation과 partial/fail-closed 상태 Token 값, authorization header와 credential-bearing URL은 보고하지 않는다.