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

모든 workflow는 첫 authoritative read 전에 authenticated adapter로 현재 사용자를 읽는다. REST adapter는 exact GET /api/v1/user를 사용한다.
Stable numeric account ID, login과 현재 workflow role을 기록한다. Transport에 따라 login 표시가 달라도 stable account ID가 같으면 같은 identity다.
예상 role identity를 확인할 수 없거나 API가 401, 403, redirect, malformed response 또는 anonymous identity를 반환하면 fail-closed한다.
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/<profile>이므로 같은 변수 이름을 사용해도 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은 보고하지 않는다.

6.0 KiB Raw Blame History